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We offer the most complete line of 
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When you need development tools, 
Intel’s selection runs the gamut. In fact, 
we offer the most extensive line avail¬ 
able for Intel architectures—from i386,™ 
♦ i486,™ i860,™ i960,™ and 186 micro¬ 

processors, to MCS®-51 and MCS-96 
microcontrollers. 

Because they’re all from Intel, our 
tools work better together to help you get to market 
quickly. No other vendor can give you a better view of 
what’s going on inside the processor. Plus, you save time by 
ordering tools from our catalog with a simple phone call. 
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Windows™/DOS Developer’s Journal 

Call For Papers 


Windows/DOS Developer’s Journal is seek¬ 
ing articles on the topics below. If you have an 
idea for a related story and experience that 
would especially qualify you to write on one of 
these topics, contact the Windows/DOS 
Developer’s Journal editorial staff for Author 
Guidelines at: 


Windows/DOS Developer’s Journal 

1601 W. 23rd St., Suite 200 
P.O. Box 3127 
Lawrence, KS 66046-0127 
(913) 841-1631 
FAX (913) 841-2624 


TOPICS 


Interpreters 


Hardware Manipulation 

■ Proposals due 12/5/91 
manuscripts due 1/13/92 

Suggested topics: Using a 
transputer board. Accessing 
hardware directly from a Win¬ 
dows application. Programming 
a floating-point array processor. 
How to write a Windows device 
driver. A universal printer device 
driver. 


■ Proposals due 1/6/92 
manuscripts due 2/10/92 

Suggested topics: Generating 
threaded code for a PC inter¬ 
preter. An interpreter replace¬ 
ment for COMMAND. COM. A minimal 
8086 Forth interpreter. A DOS 
shell for Windows. A feature 
comparison of Smalltalk, Actor, 
Liana, Object/1, KnowlegePro, 
etc. A User Report on a PC im¬ 
plementation of MUMPS. 


Debugging 

■ Proposals due 2/6/92 
manuscripts due 3/12/92 

Suggested topics: Using 

hardware debuggers, assert ()- 
style macros for Windows. Using 
protected-mode to catch stray 
pointers. Debugging NLM ap¬ 
plications. 


We prefer very practical and detailed treatments of 
real problems encountered when working on PC 
platforms. Topics should be of practical interest to 
professional developers working under MS-DOS or 
OS/2. Accompanying code may be in BASIC, Pas¬ 
cal, C, assembly, C+ + , or another language if the 
nature of the story requires it. 


We pay at rates competitive with other national 
technical journals and provide better editorial assis¬ 
tance than most. 

Proposals should include a short abstract, a one- 
page outline, and a brief resume of the author’s 
qualifications. When mailing the proposal, please 
include a hard copy and an ASCII text file on an 
MS-DOS formatted disk. 
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The objects ot Windows 
development 

Turbo Pascal for Windows comes with 
a complete library of prewritten program 
building blocks called objects. To create a 
program, simply select the objects you want 
from the included ObjectWindows™ library, 
place them in your application, and off you 
go. Before you know it, you've created your 
first Windows program complete with over¬ 
lapping Windows, pull-down menus and 
dialog boxes! 

Get the critics’ choice! 

Turbo Pascal for Windows goes the 
distance with the critics, too! David Gerrold 
in PC Techniques (July-August 1991) says, 

“If I had to pick one killer ‘app’ for 
Windows, I’d pick Turbo Pascal for 
Windows.” Windows and OS/2 Magazine 
states, “The speed of the compiler is a 
pleasure to experience.” (Sept. 1991). 
InfoWorid proclaims, “Turbo Pascal sets 
the standard for Windows programming. 
The ObjectWindows library makes (it) 
extremely easy to use.” (June 3, 1991) 

Now you can get Turbo 
Pascal for Windows for only 
$99“ from Borland (after 
a $25 manufacturer’s 
rebate*). That’s $150 off the 
suggested retail price and half 


INFO 


Turbo 

VERSION 1.0 


WORLD 
for Windows 


Criterion V/ i x Score 

Performance l”3ogBS < °l 

Programming envijonment Excellent 

Language extensions Excellent 

Debugging 1 Excellent 

OOP implementation Excellent 

Documentation Excellent 

Ease of learning Very Good 

Ease of use Excellent 

Error handling Very Good 

Support 

Support policies } Very Good 

Technical support; Very Good 

Value Excellent 

Final score 9.1 


Turbo Pascal lor Windows rfceived one of the highest scores ever 
in InfoWorid, outperforming Visual Basic. 

the price of Visual Basic! t So why limit your 
Windows development when you can go 
as far aS you want? Turbo Pascal 
for Windows. The easy way to 
go the distance. 

See your dealer today, or 
call 1-800-331-0877 now! 


Turbo Pascal® for Windows is the easy 
way to get into Windows application devel¬ 
opment and go as far as you want. Because 
Turbo Pascal for Windows gives you twice 



Visual 

Turbo Pascal 


Basic 

for Windows 

Visual interface editing 

Yes 

Yes 

Object-oriented language 

No 

Yes 

Compiled 

No 

Yes 

Built-in assembler 

No 

Yes 

Extensible 

No"’ 

Yes 

Create DLLs 

No 

Yes 

Reference to API 

No 

Yes 

Resource compiler 

No 

Yes 

Help compiler 

No 

Yes 

Speed (Sieve) 

20.21 sec. 

1.65 sec. 

Space (Sieve) 

5429 bytes 

® 1156 bytes 


"'Visual Basic can only be extended by writing Dynamic Link 
Libraries in C, C++ or Pascal. 

'“Visual Basic requires a runtime Dynamic Link Library of 272K. 


Turbo Pascal lor Windows comes with everything you could 
possibly want lor writing Windows applications easily. 

the features of Visual Basic in a faster, more 
efficient package. So you’ll never run out of 
horsepower! 

With Turbo Pascal for Windows you 
can instantly create a functional Windows 
interface without programming, using the 
included Resource Toolkit. And you can 
write your first Windows program in justjtue 
lines of code. 


BORLAND 


CODE:MF 52 1 


The Leader in Object-Oriented Programming 


‘Offer good until December 31,1991. fRebate also available from your local dealer. Dealer prices may vary. Copyright© 1991 Borland International, Inc. All rights reserved. Turbo Pascal aijid ObjectWindows are trademarks of 
Borland international, inc. bi 1432 □ Request 337 on Reader Service Card □ 
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From 

The Editor 


Welcome to the first issue of Windows/DOS Developer’s Journal. If you've been a 
reader of TECH Specialist for a while, don't worry - you'll still find the same types of 
articles, written at the same level of sophistication. The only thing that's changed is 
the name. Why? Well, to be candid, TECH Specialist was not the most descriptive of 
names (what is a tech specialist, anyway?). Windows/DOS Developer's Journal leaves 
no doubt about the content of the magazine or about who should read it. 

Remember that, no matter what the name, we depend on you to help us deter¬ 
mine which subjects to cover. If you receive a survey from us in the mail, please 
take the time to answer - that helps us figure out who you are and what you want 

On another note, I am happy to introduce Paul Bonneau as our new Windows 
Q&A columnist Paul has established a reputation among Windows programmers on 
the Internet as the person who has the best answers to the toughest Windows 
questions. If you look at this month's column (in which he creates a fix for a nasty 
Windows 3.0 bug), you will see why. I have rarely seen Paul stumped, but I am 
counting on our readers to try; please send us your Windows questions and we will 
answer as many as possible. 

We hope you find this inaugural issue of Windows/DOS Developer's Journal useful, 
interesting, and informative. 


Ron Burk 

Editor 
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NEW VERSION 


No Source? 
No Problem. 


Automatic BIOS, PSP, 
and MS-DOS 
interrupt labeling 
built-in 


Batch and Interactive 
modes 


Interactively locates 
code/data boundaries 



Dis>Doc Professional™ 


8086 to 80486 
instruction sets 
supported 


Interactive cross- 
referencing 


Creates listing only 
after disassembly is 
perfect 


New Dis # Doc Professional is your dual-mode disas¬ 
sembler to any DOS source code. It works in batch 
and interactive modes simultaneously, allowing you 
to generate the core information of even the most 
complex programs fast... and modify them even 
faster. Most programs will come apart in just two 
minutes. Imagine what you can do with a tool this 
powerful! Dis'Doc sifts through programs eight 
times for guaranteed accuracy. When code gets 
mixed up with data, our toolbox comes to the rescue 
with smart search and easy edit utilities. 

Warning: Dis # Doc Professional may change the way 
you work forever. 

Programmers who used to shy away from fixing 
outmoded programs with no source code are going 
to discover a valuable new talent: the ability to 
modify and revise codes that would cost way too 
much to start over (it's a programming manager's 
dream). Save your employer nuge new-program¬ 
ming fees and enhance your marketability. Dis'Doc 
is so easy to learn, you'll be a high-dollar hero in no 
time! 

Dis’Doc Professional is an amazing new teaching 
tool. Learn how programs work...take them apart 
and see the writing techniques that top pros use. Use 
it to assist in debugging. Hunt down viruses and 
write killers. Dis*Doc can save you years of frustra¬ 
tion, and it only costs $249.95. 


"A simple must in any serious programmer's toolbox. 
We used it to compress BIOS ' for BlueMAX. "-Bob 
Smith, President, Qualitas, Inc. 


COMPARE FOR YOURSELF! 



Dis-Doc™ 

Sourcer" 

Speed of disassembly (bytes/sec) 

822 

120 

Accuracy (code/data separation*) 

99.9% 

99.9% 

Unlimited file size 

YES 

NO 

BIOS labeling 

YES 

XTRA$$ 

BIOS/PSP file labeling 

YES 

NO 

Unpacks EXE files 

YES 

XTRA $$ 

Patcher 

YES 

NO 

Batch mode 

YES 

YES j. 

Interactive mode 

YES 

NO | 

Time it takes to customize a label 

5 sec. 

2-5 min. 

Time it takes to change data to code 

5 sec. 

2-5 min. 

*at eight passes based on a 9040 byte EXE file picked 

at random • 


Sourcer is a registered trademark of V Communication 

Inc. 



To order your Dis*Doc Professional™ disassembler 
toolkit or our $10 demo disk, simply call: 

1 - 800 - 336-1961 in US andCanada 


1-203-489-5335 voice 1-203-489-5746 fax 

or send check or money order for $249.95 plus $6 s&h to: 

RJSwantek, Inc. 

178 Brookside Road 
Newington, CT 06111-1320 USA 

MasterCard & Visa fr Shipped Immediately Via UPS Blue inside US. 

















































South Mountain Software 



) rogramming communications is a 
time-consuming, complicated, 
and sometimes tedious pro¬ 
gramming job. The task of 
creating a solid communications 
application can contain more 
surprises than a magic show. 

Professional C programmers have 
come to rely on South Mountain 
for fast, safe and efficient commu¬ 
nications functions. With a func¬ 
tion library as clean and complete 
as this one, you don’t need to 
know assembler to have complete 
RS-232 control. 

Functions too Numerous to 

Mention 

We can’t list all the many func¬ 
tions here, but our library is 
designed to support the length and 
breadth of your application’s 
need. From numerous file transfer 
protocols to intelligent modem 
control functions, we do it all. If 
you don’t see what you need in 
the features box below, call us at 
800-451-6174. We probably have 
what you’re looking for. 

Freebies 

As an added incentive and learn¬ 
ing tool, we include the full 
source code for a BBS system and 
a terminal package. Both can be 


incorporated into projects or dissected 
for programming hints. 

We have also designed and included a 
sub-system for background file transfers. 
This procedure can save you hours of ex¬ 
perimentation and frustration. 

BreakOut II Interactive 

Communications Debugger 

For serious communications application 
development, BreakOut IT-vill saveyou^ 

hours of debugging r ith your 

a PC will allow you to interact y 
comm application on a readme basis 
capturing and transmitting data. In he 
monitor mode (along with a special 
cable option) you can monitor the ^ 
comm session between any w 

on an RS-232 line. 

You will be able to spot hardware 

malfunctions and view line signals up 

115K All of this for hundreds of 

dollars less than traditional hardware 

, , price 

methods. includes cable 


Real People, Realistic Policies 

Our tech support and sales lines are 
peopled by real C programmers. They 
are able and willing to answer your ques¬ 
tions before and after your purchase. 

We offer 30-day, money-back guarantees 
on all our products, and never charge a 
royalty or run-time fee. If you’ve 


forgotten what it’s like to be treated as 
an important customer, give us a call 
today. You’ll like the change. 

Features 


4 Interrupt-driven transmit and receive 
to 115,200 Baud 

4 Simultaneous operation on up to 34 
serial ports 

4 Intelligent modem control functions 
4 XMODEM, YMODEM, YMODEM-g, 
and KERMIT 

4 XON/XOFF and hardware flow control 
4 Concurrent file transfer sessions in 
foreground/background 
4 Timer and CTRL-Break handling 
4 Extensive multi-port board support 
4 Both Microsoft C and Turbo C support 
included 


Essential Communications 
Price inc. Source $329. 

No royalties, 30-Day Money-Back 
Guarantee 

Other Products 

C-Utility, Essential Graphics, Essential B- 
Tree, ScreenStar, /*resident_C*/, 
Guido, Hold Everything 

1-800-451-6174 


□ Request 317 on Reader Service Card □ 




South Mountain Software Inc. 

76 S. Orange Ave., S. Orange, NJ 07079 
NJ 201-762-6965 Fax 201-762-0118 

Essential Graphics, Essential Communications, Essential B-tree 
C-Utility Library, Hold Everything, Breakout 2 
GUIDO, /* resident_C*/ Screen Star 
are trademarks of South Mountain Software Inc. 























■ Windows Questions And Answers 7 



Q Recently, someone on USENET asked a question about apparent memory 
leakage from multi-line edit (MLE) controls. His application would create (and 
destroy) MLE’s as the user interacted with the program. After a period of time, Win¬ 
dows would fail any request the application made to CreateUindow(). He did some 
digging and noticed that each time the program created a MLE and destroyed it, the 
MLE left behind a 16-byte block of memory in the USER heap. This is a critical 
problem, because Windows allocates important user-interface objects (for example, 
window and menu structures) in the USER heap, and that heap is limited to 64Kb. 

A The first step in tackling a problem like this is to reproduce the bug, so I wrote 
the small program in Listing 1 . To create this program, you also need the .RC 
file in Listing 2, the module definition file in Listing 3, and the makefile in Listing 4. 
All this program does is create and destroy an MLE repeatedly until the Create- 
Uindow() call returns NULL. When this happens, the USER heap is exhausted (and 
Windows will be very unstable!) 

A bug that uses up the USER heap has bad implications for any long-term Win¬ 
dows session. Even though many applications today eventually generate UAEs with 
continued use, some are quite clean, and if used exclusively have a mean-time-to- 
UAE measured in days or months, not hours, if creating MLEs (for example, by invok¬ 
ing NOTEPAD) erodes the very valuable USER heap resource, then most users will 
eventually have to reboot Once you exhaust the USER heap, the Program Manager 
will not even be able to create the windows used by the "Exit Windows?" dialog! 


Paul Bonneau 


You may address Win¬ 
dows questions to Paul in 
care of Windows/DOS 
Developer's Journal a t 
1601 W. 23rd St, Ste. 200, 
P.0. Box 3127, Lawrence, 
KS 66044-0127, or you 
may contact him via in¬ 
ternet as 

bonneauOhyper. hyper, can. 


Paul Bonneau is the senior software design engineer for Hypercube, Inc, #7-419 
Phillips St, Waterloo, Ontario, Canada, N2L 3X2. His current project is HyperChem, a 
molecular modelling software package for Windows. Paul has been developing Win¬ 
dows applications for 5 years. Much of his expertise was gained at Microsoft, where 
he implemented a library module used by all of Microsoft's major Windows applica¬ 
tions. You can reach Paul via internet as bonneauOhyper.hyper.com or via phone by 
(519) 725-4040. 
















Running the program in Listing t 
under Windows 3.0 and 3.0a verifies 
that the bug indeed exists. I am able to 
create and destroy approximately 3000 
MLEs before USER memory is exhausted. 
Your results will vary, however, 
depending on the state of your system 
when the program is run. Running the 
program on the first beta version of 
Windows 3.1, however, did not reveal 
the bug. Thus it appears this bug will 
only be a problem for versions 3.0 and 
3.0a. However, since not everyone pos¬ 
sessing these versions will upgrade to 
version 3.1, it is worthwhile to develop 
a patch for the bug. 

There are a couple of aspects of the 
bug tester worthy of mention. First, it is 
not a well-behaved program; once you 
hit the "Test” menu item, the bug tester 
will not yield control of the processor 
until the test is complete. The justifica¬ 
tion for this is that if the bug tester 
yields to another application, it would 
be impossible to obtain reproducible 
results since the other application could 
affect the amount of USER heap space 
while the test was running. If you run 
the test on a system in a known state 


(for example, right after you start Win¬ 
dows), it should report the same num¬ 
ber of MLE creations each time. Second, 
you will notice that Listing 1 creates the 
MLE with a vertical scroll bar. As it turns 
out, the bug only manifests when you 
create a MLE with a scroll bar. This clue 
becomes important in tracking the bug 
down. 

Finding The Bug 

Since the symptom of this bug is 
diminishing USER heap space, a good 
first approach is to set a breakpoint on 
LocalAllocf) and LocalFreef) , since 
the USER heap is nothing more than a 
local heap. You already know that the 
leakage is occurring sometime after 
CreateHindowf) and before Destroy- 
Mindowf) of a MLE, so a logical explana¬ 
tion would be a dangling memory 
handle. By keeping a list of the handles 
returned by calls to LocalAlloc(), and 
crossing them off when they are passed 
to LocalFree(), you can find the of¬ 
fending handle. 

I set breakpoints on the CwndTest- 
Mle() function of the bug tester (Listing 


1), and LocalAlloc() and LocalFree(), 
using the kernel debugger, WDEB386. 
The kernel debugger is an invaluable 
tool when you need to trace through 
Windows code itself. It can examine 
symbols not only from the program you 
are debugging, but also from the three 
symbol files supplied with the SDK 
(USER, KERNEL, and GDI). I always specify 
the SDK's symbols files on the com¬ 
mand line when I invoke the debugger. 

LocalAllocf) uses the current value 
of the DS register to determine which 
local heap to use. The DS register will 
be the selector (or segment, in real 
mode) of the global block containing 
the heap. Since you know the leakage 
is occurring in the USER heap, there is 
no need to pay attention to those calls 
for which DS is not equal to the USER 
data segment 

To find the USER data segment 
selector, you can use the debugger's Ig 
command. This command lists the 
selectors (or segments) in the active 
map. The active map is basically the 
current symbol file. To make a symbol 
file the current one (that is, to select 
the active map), use the w command. 
So, the command w user will make 
USER.SYM the current symbol table. The 
Ig command always lists the DGROUP 
selector last. DGROUP is a module's 
default data segment, so it will be the 
segment containing the local heap. 
Thus, the last value reported by Ig 
(after issuing w user ) will be the selec¬ 
tor of USER’S local heap. Using this 
method I obtained a selector value of 
06ED. 

You can verify that this value is in¬ 
deed USER’S default data segment by 
using the . dg command with the selec¬ 
tor value to examine the segment's at¬ 
tributes. When I executed the com¬ 
mand .dg 6ed I got the report shown 
in Figure 1. This result verifies that 
selector 06ED belongs to USER and ref¬ 
erences a data segment 

Stepping through the breakpoints in 
the debugger showed that, between 
the call to CreateHindowf) and 
DestroyUindowf) for the MLE, seven 
calls were made to LocalAllocf), of 
which USER made three. All three calls 
used the LMEM_FIXED flag, which in¬ 
structs LocalAllocf) to allocate im¬ 
movable memory, and also to return a 
pointer to that memory. Without 


Listing 1 (mlebug.c) 


/**★*★★**★***★★***★★*★**★*★★★**★**★★**★**★***★***★★★★★i 

/* mlebug.c */ 
/* -- This program attempts to create and destroy */ 
/* Multi Line Editltems to test if the leaky MLE */ 


/* 


bug is present. 


fdefine N0C0MM 
linclude <windows.h> 

#include <stdio.h> 

LONG CwndTestMle(HWND); 

int FAR PASCAL WinMain(HANDLE, HANDLE, LPSTR, 
int); 

LONG FAR PASCAL WndProc(HWND, WORD, WORD, DWORD); 

/* Status message. */ 

static char szMessage[80] = "Ready"; 

/* Maximum of MLE create/destroy pairs. */ 

#define cwndTest OxlOOOOL 

Idefine szMleBug "MLEBug" /* Class name. */ 

#define IDM_TEST 1 /* Menu command. */ 

int FAR PASCAL 

WinMain(HANDLE hins, HANDLE hinsPrev, LPSTR lsz, int w) 
/**★★★**★★★★***★★*★★★★★★★★***★*****★*********★****★*★★/ 


/* -- hins 
/* -- hinsPrev 
/* — lsz 
/* -- w 

/ 


This program's instance. */ 
Previous program's instance. */ 
Command line I was invoked with. */ 
ShowWindow command. */ 


*★★***★★★★★★**★**★*•★*★★★★★*★★★★*★*★★*•★*★★*■*•*★★★★*★★*★/ 


( 

MSG 

POINT 


msg; 

pt; 


The MLE Bug Tester 
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Listing 1 — Cont’d 

if (hinsPrev == NULL) 

{ 

WNDCLASS wcs; 

/* First instance is responsible for */ 

/* registering a class. */ 
wcs.style = CS_HREDRAW | CS_VREDRAW; 
wcs.lpfnWndProc * WndProc; 
wcs.cbClsExtra = 0; 
wcs.cbWndExtra = 0: 
wcs.hlnstance * hins; 
wcs.hlcon = NULL; 

wcs.hCursor = LoadCursor(NULL, IDC_ARR0H); 
wcs.hbrBackground = 

GetStockObject(WHITE_BRUSH); 
wcs.lpszMenuName = szMleBug; 
wcs.lpszClassName = szMleBug; 

if (!RegisterClass(&wcs)) 
return FALSE; 

} 

*(L0NG *)&pt = GetDialogBaseUnitsO; 
if (CreateWindow( 
szMleBug, 

“MLE Bug Tester", 

WS_0VERLAPPEDWIND0W | WS_VISIBLE, 

CW_USEDEFAULT, 

w,' 

pt.x * 40, /* 40 chars wide. */ 

pt.y * 5, /* 5 char high. */ 

NULL, 

NULL, 
hi ns, 

NULL) == NULL) 
return FALSE; 

while (GetMessage(&msg, NULL, 0, 0)) 

{ 

TranslateMessage(&msg); 

DispatchMessage(Smsg); 

} 

return 0; 

) 

LONG FAR PASCAL 

WndProc(HWND hwnd, WORD wm, WORD mpl, DWORD mp2) 


/* -- WindowProc for our main window. */ 
/* -- hwnd : Main window. */ 
/* -- wm : Message type. */ 
/* -- mpl, mp2: Message parameters. */ 


y********fr****ik*******1hHHHhk******iHrt'<H>***’************ j 

{ 

switch (wm) 

{ 

default: 

return DefWindowProc(hwnd, wm, mpl, mp2); 

case WM_DESTROY: 

PostQuitMessage(O); 
break; 

case WM_COMMAND: 

if (mpl -- IDM_TEST) 

{ 

LONG cwnd - CwndTestMle(hwnd); 
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Listing 1 — Cont’d 

sprintf(szMesssge, “%1d edits: Vs", cwnd, 
cwnd == cwndTest ? "Ok" : 

"Leaky edit"); 

InvalidateRect(hwnd, NULL, TRUE); 

} 

break; 

case WM_PAINT: 

{ ' 

PAINTSTRUCT wps; 

RECT rect; 

BeginPaintfhwnd, Awps); 

GetClientRect(hwnd, Arect); 

DrawText(wps.hdc, szMessage. -1, Arect, 

DT_CENTER | DTJCENTER | DT SINGLELINE); 
EndPaint(hwnd, Awps); 

) 

break; /* End case WM_PAINT. */ 

) /* End switch wm. */ 

return OL; 

) 

LONG 

CwndTestMle(HWND hwndReport) 
/*****************************************************/ 


/* -- We do the actual work here. */ 
/* -- Create and destroy an MLE window, repeatedly, */ 
/* cwndTest times or until CreateWindowO fails. */ 
/* -- Return the number of MLE's we were able to */ 
/* create. */ 
/* -- hwndReport : Window to display results into. */ 


/*****************************************************J 

( 

LONG iwnd; 

HANDLE hi ns; 

hins * GetWindowWord(hwndReport, GWW_HINSTANCE); 
for (iwnd * 1L; iwnd <= cwndTest; iwnd++) 

( 

HWND hwnd; 

if ((hwnd * CreateWindow( 

"edit", 

NULL, 

WS_CHILD | ES MULTILINE | WSJSCROLL, 

0 . 0 . 0 , 0 , 

hwndReport, 

1 , 

hins, NULL)) •• NULL) 
break; 

DestroyWindow(hwnd); 

if (iwnd V 10L — OL) 

( 

/* Display every 10 times. */ 
sprintf(szMessage, "VId MLEs", iwnd); 

InvalidateRect(hwndReport, NULL, TRUE); 
UpdateWindow(hwndReport); 

1 

} 

return iwnd - 1L; 

) 

/* End of File */ 


Listing 2 (mlebug.rc) 

/*****************************************************f 

/* mlebug.rc */ 

/* -- Resource script file for mlebug program. */ 

^******* **********************************************j 

finclude <windows.h> 

MLEBug MENU 
BEGIN 

MENUITEM "ATest", 1 
END 


LMEMFIXED, LocalAlloc() returns a 
handle which must be passed to 
Local Lock () to retrieve a pointer. 

As surmised, the second call to 
LocalAllocf) returned a pointer that 
was never freed. Armed with this 
knowledge, on the second iteration of 
CwndTestMlef), I set a breakpoint on 
the instruction following the call to 
LocalAlloc(). You can find the return 
address of a FAR function by using the 
command dw ss:sp l 2. This dumps 
the first two words from the stack, 
which is the return address. I obtained 
an address of 0595:4139. 

Once I reached the breakpoint I used 
the u command to disassemble some 
instructions following the return. The 
first two were: 

595:4139 MOV DI.AX 

595:413B MOV WORD PTR [SI+OA],DI 

By convention, 16-bit values are 
returned in the AX register, so these in¬ 
structions stuff the handle returned by 
LocalAllocf) into offset 000A from the 
value in the SI register. Examining the 
value of SI revealed it to be the same 
value returned by the first call to 
LocalAllocf). An educated guess indi¬ 
cated that this was the MLE’s window 
handle. Window handles are nothing 
more than near pointers into the USER 
heap. The value returned by Create- 
Windowf) confirmed the guess. So, the 
pointer returned by the second call to 
LocalAllocf) was being stored at of¬ 
fset OxOOOA in the MLE’s window struc¬ 
ture. 

I next used the k command to dump 
the call stack. It showed that address 
0595:4139 was at offset ADJUSTUIN- 
DOWRECTEX + 01 BO. This does not mean 
that AdjustUindouRectExf) was the 
name of the function, since the symbol 
table does not include private Windows 
functions. But, the second address on 
the call stack was defwindohproc+0299. 
This is the address the current function 
will return to. So, once again using u to 
disassemble, and starting a bit before 
DEFUINDOUPROC+0299, I found the actual 
call to the mystery function, and hence 
its address. I disassembled 0020 bytes 
from the function’s return address (u 
DEFUIND0HPR0C+299- 0020) to find the 
call immediately preceding the return: 


Page 10 — Windows/DOS Developer’s Journal 


December 1991 






Figure 1 


Address Arena Size Type 

Owner Handle LRU Links 

Seg|Rsrc 

91c20: 160 6360b DATA 

USER (06EE.1.L1.P1) 

2C 


Listing 3 (mlebug.def) 

;; mlebug.def ;; 

;; — Linker definition file for mlebug program. ;; 

NAME 

MLEBug 

DESCRIPTION 

'MLE Bug Tester' 

EXETYPE 

WINDOWS 

STUB 

'WINSTUB.EXE' 

CODE 

PRELOAD MOVEABLE DISCARDABLE 

DATA 

PRELOAD MOVEABLE MULTIPLE 

HEAPSIZE 

1024 

STACKSIZE 

EXPORTS 

10240 

WndProc @1 


Module Definition File for mlebug. c 



Listing 4 (makefile.bug) 

######################/########/####################### 

## makefile 

ff 

## -- Project file for mlebug program. ## 

all: mlebug.exe 


mlebug.obj: mlebug.c 


cl -c -AM -Gsw -Oas 

-Zdpe -W3 mlebug.c 

mlebug.exe: mlebug.obj mlebug.def mlebug.rc 

link /N0D/m mlebug,, 
rc mlebug 

, libw mlibcew. mlebug.def 

mapsym mlebug 

Makefile for mlebug. c 


Listing 5 (win.h) 

/******************************************************/ 

/* win.h */ 

/* -- USER window structrure. */ 

^******************************************************J 

typedef struct 
( 


HWND 

hwndNext; 

/* 

Next sibling. */ 

HWN0 

hwndChild; 

/* 

First child. */ 

WORD 

unknown 1; 



WORD 

unknown2; 



WORD 

unknowns; 



WORD 

unknown4; 



HANDLE 

hmemTask; 

/* 

Task database handle. */ 

WORD 

unknown5; 



WORD 

unknown6; 



WORD 

unknown7; 



HWND 

hwndOwner; 

/* 

Owner (popup's only). */ 

RECT 

rectWindow; 

/* 

Rect. (screen co-ords). */ 

RECT 

rectClient; 

/* 

Rect. (client co-ords). */ 

WORD 

unknown8; 



WORD 

unknown9; 



DWORD 

rgfExStyle; 

/* 

Extra window style. */ 

DWORD 

rgfStyle; 

/* 

Window style. */ 

HMENU 

hmenu; 

/* 

Menu handle/control id. */ 

WORD 

hwndText; 

/* 

Text window. */ 

HWND 

hwndParent; 

/* 

Parent window for child. */ 

HANDLE 

hins; 

/* 

App's instance handle. */ 

FARPROC 

lpfn; 

/* 

Window procedure. */ 

WORD 
} WND; 

rgUser[l]; 

/* 

Start of user data area. */ 


Internal WND Structure 
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059d:0550 CALL 0595:4124 


Listing 6 (mlefix.c) 


/★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★/ 
/* mlefix.c */ 

/* - Program to fix the leaky MLE bug. */ 

/ 


*********************★*******************************/ 


Idefine N0C0MM 
finclude <windows.h> 
linclude "win.h" 

HANDLE hmemUser; 

FARPROC lpfnMLEFilter; 

LONG FAR PASCAL MLEFi1 ter(WORD, WORD, WORD, DWORD); 
int FAR PASCAL LibMain(HANDLE, WORD, WORD, LPSTR); 

int FAR PASCAL WEP(short); 

int FAR PASCAL 

LibMain(HANDLE hins, WORD ds, WORD cbHeap, LPSTR lsz) 
/★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★/ 
/* - hins : This library's instance. */ 

/* - ds : The library's default data segment */ 

/* - cbHeap : Size of out local heap. */ 

/* - lsz : Command line invoked with. */ 

j★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★j 


WORD 

WNDCLASS 


wVersion 

wcs; 


= GetVersion(); 


0) 


/* Only need to fix this bug for version 3.0. */ 
if (LOBYTE(wVersion) != 3 || HIBYTE(wVersion) 1= 
return FALSE; 

/* Get USER'S default data segment. */ 
if ((hmemUser = LoadLibraryCuser.exe")) == 0) 
return FALSE; 

/* Superclass the edit class. */ 

GetClassInfo(NULL, “edit", &wcs); 

UnregisterClass("edit", NULL); 
lpfnMLEFilter = (FARPROC)wcs.lpfnWndProc; 
wcs.lpfnWndProc » MLEFiIter; 

RegisterClass(&wcs); /* This better work! */ 

return TRUE; 

} 

int FAR PASCAL 
WEP(short wCode) 

/★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★/ 
/* - The usual do-nothing stub. */ 

j******** 

{ 

return FALSE; 

) 


LONG FAR PASCAL 

MLEFilter(W0RD hwnd, WORD wm, WORD mpl, DWORD lmpl) 

/★★★★♦★★★★★★★♦★★★★★★★★★★★★★★★★★★★★★♦★★♦★★♦★★★★★★★★★★★•Ary 


/* - Superclasser for MLE's. */ 
/* - hwnd : Main window. */ 
/* - m : Message type. */ 
/* - mpl, mp2 : Message parameters. */ 


/★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★j 

{ 

LONG 1Val; 

lVal » CallWindowProc(lpfnMLEFilter, hwnd, wm, mpl, 
lmpl); 

if (wm == WM_NCCREATE && 

(GetWindowLong(hwnd, GWL_STYLE) & 

(WSVSCROLL | WS_HSCROLL))) 

{ 

WORD dsUser « HIWORD(GlobalLock(hmemUser)); 
WORD dsLocal; 


DLL to Fix Windows MLE Bug 


Who’s Not Freeing Memory? 

The question then was why the 
memory was not being freed. My first 
guess was that a NULL value was some¬ 
how overwriting the pointer at offset 
OxOOOA. Perhaps when the MLE was 
destroyed it tested the value at that of¬ 
fset for NULL, and called LocalFree() if 
it was not NULL. 

Once again, the debugger comes to 
the rescue. You can use the debugger 
to set a hardware watchpoint on a 
write to an arbitrary memory address. 
The syntax is: 

br w{1|2|4} address 

where w specifies to look, for a write to 
memory and 1,2, or 4 specifies the size 
in bytes of the operand to watch. 
Whenever a write to the address oc¬ 
curs, the hardware generates an inter¬ 
rupt that breaks to the debugger. 

After the first call to LocalAlloc(), 1 
set a watchpoint at offset OxOOOA from 
the MLE window handle in the SI 
register. As expected, the code follow¬ 
ing the call to Local Alloc () from the 
function at 0595:4124 triggered the 
watchpoint However, what was unex¬ 
pected was that right after the third 
LocalAlloc() call, the watchpoint was 
hit again. In fact, it turned out to be the 
same piece of codel So, this function at 
0595:4124 was being called twice. On 
each call it would call LocalAllocf) 
and stuff the pointer into offset OxOOOA 
of the MLE's window structure. The 
second call to this mystery routine was 
obliterating the handle from the first 
call, which then became a dangling 
pointer! 

Why was the same function being 
called twice? In an attempt to answer 
this question, I decided to place a 
breakpoint on the window procedure 
for the MLE itself. By doing this, I could 
monitor the messages it was receiving, 
and see which messages triggered the 
call. Now, unlike Windows 2.x, Windows 
3.x window procedures for system 
global classes no longer have symbols, 
so I had to dig a bit to discover the ad¬ 
dress of the MLE's window procedure. 

Fortunately, one of the fields of Win¬ 
dows internal window structure is the 
address of the window procedure. Over 
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time, 1 have constructed a definition of 
the window structure used inside USER. 
I will not go into how to determine 
those offsets here, since that could 
comprise the contents of an entire ar¬ 
ticle. Listing 5 shows the structure with 
the fields definitions I have determined 
so far. 

Since the address of the window 
procedure should be the same for 
every window of the same class, I could 
step over a call to CreateWindow() to 
obtain a MLE window handle. On the 
next call to CreateUindow(), it returned 
the window handle 4F58, so the ad¬ 
dress 06ED:4F58 is the beginning of 


USER’S window structure for the MLE 
The window procedure is at byte offset 
003A from the beginning of the struct, 
and the value I obtained was 
0655:0000. 

Before the next iteration of the loop 
in CwndTestMle() I set a breakpoint on 
the MLE window procedure. The kernel 
debugger allows you to associate a 
command with a breakpoint I wanted 
to see the arguments to the MLE's win¬ 
dow procedure, so I used: 

bp 0655:0000 "dw ss:sp 1 7" 
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Listing 6 — Cont’d 

_asm mov dsLocal, ds; /* Save ds. */ 

_asm mov ds, dsUser; /* Get USER ds. */ 

/* Free dangling USER heap memory. */ 
if (((WND *)hwnd)->unknown4 != 0) 

I 

LocalFree(((WND *)hwnd)->unknown4); 

((WND *)hwnd)->unknown4 = 0; 

1 

_asm mov ds, dsLocal; /* Restore ds. */ 

/* In case of REAL mode. */ 

G1obalUniock(hmemUser); 

) 

return lVal; 

} 

/* End of File */ 


Listing 7 (mlefix.def) 

;; mlefix 

def ;; 

;; -- Linker definition file for mlefix dll. ;; 

LIBRARY 

MLEFix 

EXETYPE 

WINDOWS 

CODE 

PRELOAD MOVEABLE DISCARDABLE 

DATA 

PRELOAD SINGLE 

HEAPSIZE 

0 

EXPORTS 


WEP 

61 RESIDENTNAME 

MLEFilter 62 


Module Definition file for mlefix. c 


Listing 8 (makefile.fix) 

####################################################### 

## makefile ## 

## -- Project file for mlefix program. tt 

all: mlefix.exe 

mlefix.obj: mlefix.c 

cl -c -AMw -Gsw -Os -Zdpe -W3 mlefix.c 

mlefix.exe: mlefix.obj mlefix.def 

link /m mlefix 1ibentry,mlefix,,1ibw mdllcew,mlefix 
rc mlefix.exe 

Makefile for mlefix. c 
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support business. Forever! 

Make your product more functional 
and competitive by using SLATE'S 
advanced text features: 

• Support multiple printers on the same 

system. 

• Output to parallel printers, serial printers, 

DOS files/devices, DOS print spooler, 
and Novell network printers. 

• Include end user's soft fonts. 

• Support cartridge fonts. 

• Support proportional fonts 

• Support scalable font printers. 

• Set exact print positions. 

• Color printing 

• Kerning, leading, overstrike, underlining, 

and strike through. 

• Automatic character set conversion. 

SLATE with Graphics adds advanced 
graphic printing features: 

• Print images from the screen, PCX or TIFF 

files, or custom image systems. 

• Scale and Rotate the printed image. 

• Print grey scale and color images. 

• Intermix text and graphics. 

SLATE is a set of C or Basic libraries 
with over 170 text printing functions, 

a Database of over 750 printers, 
and End User configuration and 
testing programs. 

SLATE with Graphics adds over 60 
graphic printing functions. 

Call now for a complete developer's 
information kit. Order SLATE for 
only $299 or SLATE with Graphics 
for $448 with our risk free, 30 day 
return policy. 

We accept Visa, MasterCard, COD's or PO's 
from qualified companies. Source code, 
maintenance, and site licenses are available. 

800 - 346-3938 

The PO Box 26195 

Columbus, OH 43226 
614-431-2667 
FAX 614-431-5734 


Symmetry 

Group 


As already mentioned, the first two 
words on the stack are the return ad¬ 
dress. The next five words are the 
parameters to the window procedure: 

WindowHandle - 1 word 

MessageNumber - 1 word 

wParam - 1 word 

lParam - 2 words 

Note however, that since a window 
procedure always uses the PASCAL call¬ 
ing convention, the caller pushes the ar¬ 
guments on the stack in reverse order. 

The message number that triggered 
the first call to 0595:4124 was 0081, 
UM_NCCREA TE. Looking at the return ad¬ 
dress, the caller was DEFUIN- 
DOUPROC+0299. The next message to 
next trigger the call to 0595:4124 was 
OOOl, MM CREATE. Examining its return 
address revealed the caller to be at 
067d:016E. The k command showed 
this was in the segment EDMLONCE, one 
of the edit control's code segments. 

This was very suspicious, since both 
of these messages are part of initializa¬ 
tion, but the same function was being 
called for both. Could the bug be due to 
something as simple as an extra call to 
an initialization routine? 

On the next call to CreateUindow(), 
I set a breakpoint on DefUindowProc(). 
Sure enough, it was being called to 
handle UM_NCCREATE. Stepping through 
the tests that comprise the big switch 
statement, I found that when it got to 
the UMJiCCREATE case, it performed a 
test and then called 0595:41241 

It looked like both the MLE and Def¬ 
UindowProc () were performing the 
same initialization. Fortunately, 
Microsoft supplies the actual code for 
DefUindowProc () with the sample sour¬ 
ces shipped with the SDK. DefUindow¬ 
Proc () executes the following code for 
the UMJICCREATE case of the big switch 
statement 

case WMJCCREATE: 
if (TestWF(hwnd, (WFHSCROLL 
| WFVSCROLL))) 
if (InitPwSB(hwnd) == NULL) 
return((LONG)FALSE); 

Now I had a name for the mystery 
routine at 0595:4124-. InitPwSBf). Def¬ 
UindowProc () calls it for those windows 


possessing a vertical or horizontal 
scrollbar. Unfortunately, someone at 
Microsoft also coded in a call to this 
routine from the MLE's UM_INIT in¬ 
itialization, after it had already passed 
off the UMNCCREATE message to Def¬ 
UindowProc (). 

The obvious way to fix this bug is to 
somehow free the dangling memory 
left behind by the first call to 
InitPwSB(). The ideal time would be 
immediately following DefUindow¬ 
Proc ()’s processing of the UM NCCREATE 
message. To make sure it would be 
safe to do this, I set a hardware 
watchpoint for any read to the pointer 
at offset OOOA in the MLE's window, it 
was not hit until the next call to 
InitPwSBf). The memory allocated by 
the first call was truly abandoned; after 
allocation it was never again refer¬ 
enced. 

The Fix 

Once I understood the problem, I 
could fix it The obvious solution would 
be to superclass the MLE, and after 
passing it the UM_NCCREATE message, to 
extract the pointer at offset OOOA and 
cail Local Free () to free it To super¬ 
class a system-wide class requires the 
superclass routine to reside in a module 
that is guaranteed to exist for the 
lifetime of the Windows session. The 
simplest way to do this is to create a 
DLL that installs the superclasser in its 
initialization code. Since the module 
needs to exist for the entire windows 
session, you should add it to the load= 
line ofUIN.INI. 

Listing 6 presents the source for the 
DLL The module definition file for this 
DLL is in Listing 7 and Listing 8 contains 
the makefile. During initialization, the 
DLL tests the version of Windows, and 
does nothing if it is not version 3.0. 
Since the bug only occurs for MLEs pos¬ 
sessing scrollbars, the superclass routine 
tests for them and frees the dangling 
memory if it is a MLE with a scrollbar. 
Rerunning the bug tester after installing 
the DLL shows that the DLL fixes the 
bug. And finally, I now know with what 
to replace the unknown4 field of the UND 
structurel □ 
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Designing Network-Friendly Software 

Kingsley W. Hill 


Nothing irritates a network, manager or administrator more than software 
that misbehaves on the network. The meteoric rise in strategic importance of 
networks in today's business has made it more and more important for 
programmers to write software for the LAN environment 

You can approach writing network software or migrating standalone 
software in several ways with very different results. One end of the spectrum is 
software that runs on a network the same way it runs on a standalone, save 
perhaps for some consideration for file locks. The other end of the spectrum is 
software written using the Application Program Interface (API) for the specific 
target network environment and taking full advantage of all the resources af¬ 
forded it 

The first approach is not acceptable in today’s world, and the second re¬ 
quires a large commitment of time and program design resources. This discus¬ 
sion will focus in the middle. With some simple tools and consideration for the 
network supervisor as well as the network user, you can write network-friendly 
software with relative ease. 



Leave Only Your Footprints 

Most networks are used to run many different application 
programs. With such vast resources, users are likely to use 
more than just one program during the day. It is simply com¬ 
mon courtesy to write applications that leave 
the workstation in the same condition your ap- 
plication found it in. If the video was in 24x80, 
^ 256 color but your software requires some¬ 

thing else, go ahead and change it, but save 
the existing video mode upon entry and re¬ 
store it upon termination. The same advice ap¬ 
plies to the keyboard, if NUM LOCK is on and 
SCROLL LOCK is off when your program starts 
up, restore that state when your program ter¬ 
minates. 

Kingsley Hill is the founder and president of 
Network Support Center, Inc, a network support 
and management service in Washington, D.C An 
honors graduate of George Washington Univer¬ 
sity and a veteran of 17 years of computer ex¬ 
perience, Kingsley designed much of the technol¬ 
ogy and techniques used by the company. You 
may contact him by mail at Network Support 
Center, Inc, 4041 Powder Mill Rd., Calverton, MD 
20705, or by FAX at 301-595-3477. 
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With the myriad resources on the network, most networks 
employ a menu system to help users find needed applica¬ 
tions. Some of the less sophisticated menu programs expect 
applications to terminate in the same drive and directory as 
they started in. Because networks allow the assignment of 
virtual drive identification letters to any combination of serv¬ 
er/volume/directory path sequences, the user (or the menu 
software) could be totally disoriented by a program that ter¬ 
minates in an unfamiliar place. 

Many factors may dictate that your software load a TSR or 
device driver in order to run. As software becomes more com¬ 
plex and client/server computing becomes more common, the 
need for loading memory managers and client intercept 
software (such as Btrieve) becomes greater. Remember 
though, users may be planning on running another program 
needing a lot of memory or other drivers when they are 
through with your application. Therefore, unload those drivers 
and TSRs. Use of the public domain MARK and RELEASE 
programs is often sufficient to eliminate any program flotsam 
or jetsam left behind. 

Installation Faux Pas 

Network administrators are often not computer experts 
and, if they are, they are usually overwhelmed with situations 
requiring their attention. A few simple steps in planning 
software installations can make their life a little easier. 


Networks have significantly different security requirements 
than most standalone PCs. Network administrators must as¬ 
sign users certain rights to certain parts of the network to 
safeguard the network operating system, the application 
software, and other people’s work. Software that requires 
write access to the root directory of a volume for normal 
operation is likely to require the supervisor to compromise 
network security so that software can run. Many unsophisti¬ 
cated administrators will do this just to get the software run¬ 
ning, unaware that they are putting their systems are put in 
jeopardy by the practice. 

Allow the supervisor to select the installation drive and 
directory during the install process. Do not expect the program 
user to have any rights to any other directory than the one 
your program is installed in. While the path to your software 
will probably not change, remember that drive letters are 
easily changed since they are only virtual identifiers (like 
those created using the DOS SUBS ritute command). Providing 
the user an easy way to change drives is a desirable feature. 

Software install programs often insist on modifying 
AUTOEXEC.BAT and CONFIG.SYS. Do not change these files 
without permission. If permission is not granted then create 
batch fragments that the supervisor can use to modify user's 
initialization files. In fact, this is good practice in any case since 
it is sometimes difficult to tell what changes a specific installa¬ 
tion routine has made. In summary, do not assume that the 


C++/ Views 


for Microsoft Windows 


C++/Views is a development tool for C++ programmers 
that not only redyces the complexity of Microsoft 
Windows 3.0 but also slashes development time 
by up to 75%. 

Delivers on the promise of Object-Oriented K 
Programming (OOP). 

Encapsulates more MS Windows 3.0 functionality titan any 
other tool on the market today. Get MS Windows 
applications off to a fast start with a framework'of 
over +5 tested and ready-to-go C++ classes. 


Provides support for the entire project. 

Comes with a complete OOP development environment 
including the first hilly functional C++ class hierarchy 
Browser. Also includes an Interface Generator for building 
C++ dialog classes and a Documentor for automatically 
producing high quality documentation of your classes. 

Integrates leading-edge technology. 

Combine C++ View s .with Borland C++ or Zortech C++ 

for a .cost-effective and highly productive development 
environment for building your next generation software 
systems. d 


Has the most complete C++ class library for MS 
Windows Development. v 

Get started with graphical user interface classes .such as 
windows, views, bitmaps, dialog boxes, menus, popup 
menus, graphics, regions, pens, crushes, controls, buttons, 
listboxes, valuators, editors, printers and much more, 

Organize your data with foundation classes such as \ 
containers, collections, sets, dictionaries, files, strings, \ 
streams and so-on. Use other classes to manage the \ 
persistance of ojpjects across files, to perform serial 
communications, and’to activate timed events. 

CNS, Inc., Software Products Dept. 

1250 Park Road, Chanhassen, MN 55317, (612)-474-7600+ FAX (6f2)-474-6737 

^ © Copyright 1990 CNS, Inc. All rights reserved. Microsoft is a registered trademark of Microsoft Corporation. 


Pays for itself on even the smallest project. 
Only $495.00 with no royalties." 

Comes complete with source code. 

C++/Views 

from CNS, Inc. 
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machine being used for the install is the one to be used for 
day-to-day operation of the program. 

Test any installation software and installation instructions 
as you would your program. For example, in a Novell Netware 
environment, files that are to be shared need to be marked 
shareable using the FLAG command. Network administrators 
who install network software but do not FLAG the files will 
find the software works fine for them, but fails when multiple 
users start trying to access it. 

There is a lot to be said for software that loads its ex¬ 
ecutables and overlays in one directory, look-up tables, 
samples, or tutorials in another directory, and datafiles in a 
third. This allows the administrator of a network more 
flexibility. It also allows the administrator 
the opportunity to grant only the 
needed access privileges to each direc¬ 
tory. If all program and datafiles are 
loaded into one directory, the ad¬ 
ministrator will probably have to grant 
all rights to that directory to all users. 

This gives the users the ability to delete 
the program files unless steps are taken 
to prevent it such as marking the files 
read-only or execute-only. 

The Sky’s The Limit 
To Resources 

In the standalone world, most com¬ 
puters have one or two printers. Printers 
are always attached to the same port 
and the type of printer is fairly static. 

Enter the joyful world of the network, 
where every port can talk to any printer 
(even ports you don't have), the printers 
can change from day-to-day or minute- 
to-minute, and the program can be at¬ 
tached to as many printers as the net¬ 
work allows. In writing programs for net¬ 
works, assume that each user will use a 
different printer and that the users may 
want to switch from one printer to 
another regularly. Your software should 
be able to recall the setup of the printer 
for a given user wherever and whenever 
that user logs on to the program. Your 
software should also allow for easy reas¬ 
signment of printers by the user. HP 
Laserjets and compatibles are, by far, the 
most common printers on networks and 
every program should be able to talk to 
them. 

Your program has two choices in 
regard to talking to network printers. It 
can communicate directly with the net¬ 
work queue by employing the network 
API, or it can print to a port that has 
been redirected to a network device 
(using Novell CAPTURE, Banyan SETPRINT, 
etc). Printing to a redirected port is 
generally foolproof, assuming someone 


has turned on the redirection (either the software, the user, a 
login script or batch file). There is no clear indication to a 
casual user that a printer on a redirected port is ready. In fact, 
most systems require the user to leave your program and run 
the redirector program to get the printer status. Your program 
should at least verify that the desired port exists, to avoid 
problems with ports that are not redirected properly. 

Most redirectors can operate from a command line, in 
which case your program can execute the redirector directly 
to print the status. Here are the commands for Novell and 
Banyan networks, from within a dBASE clone or from Microsoft 
C: 


int f(n) 
int n; 
f 

int result; 

if( n == 1 p result = 0; 
else ifC n > 0 ) result = 1; 
else if( n < 0 ) result = 2; 
return result; 

I 


This function has a slight flaw. Can you spot it? 


PC-lint will catch this and many other 

C bugs. Unlike your compiler, PC-lint 
looks across all modules of your appli¬ 
cation for bugs and inconsistencies. 

New - Optional Strong Type Checking 
and variables possibly not initialized. 

More than 330 error messages. More 
than 105 options for complete] cus¬ 
tomization. Suppress error messages, 
locally or globally, by symbol name, by 
message number, by filename,] etc. 
Check for portability problenis. Alter 
size of scalars. Adjust format of error 
messages. Automatically generate ANSI 
prototypes for your K&R functions. 


Attn; Power users with huge programs. 

PC-lint 386 uses [DOS Extender 
Technology to access the full storage 
and flat model sjjeed of your 386. Now 
fully compatible kvith Windows 3.0 
and DOS 5.0 

PC-lint 386-$239 
PC-lint DOS - OS/2 - $139 

Mainframe & Mini Programmers 

FlexeLint ill obfuscated source 
form, is available for Unix, OS-9, 
VAX/VMS, QNX, IBM VM/MVS, 
etc. Requires only K&R C to com¬ 
pile but supports ANSI. Pricing 
starts at $798. Call for details. 



3207 Hpgarth Lane, Collegeville, PA 19426 

CALL TODAY (215)584-4261 Or FAX (215)584-4266 

30 Day Money-back Guarantee. 


PA add 6 % sales tax. 
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If you need to create 
numerical solutions beyond 
640K on DOS and unleash 
386 or 486 power, we have 
some real good news for you. 

CSL32 is a brand new version of CSL 
for 32-bit, extended-DOS or window 
programming, with the Watcom C 
386 or Intel C 386/486 compiler. 
Call Now! Find out about our 
CSL32 Introductory Offer. 

Using CSL32 with the Intel or 
Watcom compiler, you may now 
build programs, in a flat memory 
model up to 4 gigabytes, which 
include numerical solutions for 
extended DOS or Microsoft 
Windows. 

CSL is a distinguished C library 
for numerical solutions. 

\ 

O Over 500 functions 
O Mature & Reliable 
O Source Code Option 
O Guiding Examples 
O Application Notes 
O Validated Code 
O Easy to Use 
O Maintenance Option 
O Runtime Distribution Rights 
O CSL32 is compatible with CSL 

CSL versions are also available for 
DOS, SCO UNIX V/386, XENIX, 
ESIX, HP/Apollo and SunOS. Call 
Eigenware to obtain CSL parts list 
and pricing information. 

CSL, CSL32 and Eigenware are registered trademarks of 
Eigenware Technologies. Other brand and product names are 
trademarks or registered trademarks of their respective holders. 
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NOVELL: 

XBASE 

RUN CAPTURE SHOW 
MsC 

SPAWNLP(P_WAIT, "CAPTURE", 

"CAPTURE","SHOW",NULL) 

BANYAN 

XBASE 

RUN SETPRINT ? 

MsC 

SPAWNLP(P_WAIT, "SETPRINT", 
"SETPRINT",“LPT1", NULL) 

After all this about network printers, 
beware of the local printer. Every once 
in a while, your user wants to use a 
local printer, if the local printer is con¬ 
nected to a port that is normally 
redirected to a network printer, you 
have to be prepared to deactivate the 
redirector software. 

File Access 

File access is usually the first thing 
programmers writing for a network en¬ 
vironment try to tackle. After all, 
everyone knows that two programs 
cannot write the same record at the 
same time. The simplest approach is to 
lock the file when you need to write to 
it 

Every network operating system and 
network-oriented database manage¬ 
ment system supports file locks. File 
locks are perfectly adequate for most 
word processing systems and other sys¬ 
tems that operate on whole files at a 
time, but are woefully inadequate for a 
multiple access database. 

Database software should lock an 
entire file only when absolutely neces¬ 
sary and unlock the file as soon as pos¬ 
sible. Your program should also avoid 
interacting with the user or other 
peripherals while it has a file locked. 
The user may have walked away from 
the machine, or the printer might be of¬ 
fline, and, until the problem is fixed, the 
file will be totally unavailable. 

Record locks are far more flexible 
than file locks and significantly more 
forgiving. Remember, however, especial¬ 
ly in an environment that allows multi¬ 
ple record locks, to explicitly unlock 


records you no longer need. Some net¬ 
work operating systems do not auto¬ 
matically release record locks even 
after an application terminates or 
breaks a network connection. This can 
lead to a large number of orphan locks 
which may require action from the net¬ 
work administrator, or may even re¬ 
quire everyone to terminate all 
software accessing the database in 
order to completely close the file. 

Getting To Know You 

A program starting on a network 
should do its best to determine its en¬ 
vironment Is it on a network? Is there a 
local printer? Is there a redirected 
printer? 

A network is a different animal. In 
the standalone world it was acceptable 
to force users to be responsible for 
their own mistakes. That is, if a pro¬ 
gram resided in a directory and a user 
inadvertently typed ERASE *. *, it was 
too bad. On a network, though, the im¬ 
plications of such an action are far 
more widespread. First, the error can af¬ 
fect many more people than just the 
person making the mistake. Second, 
networks have become a strategic 
asset in many companies, deeply in¬ 
tegrated into the workings of the or¬ 
ganization, an organization that could 
easily collapse should an extended net¬ 
work failure occur. Making it easy for 
network administrators to secure their 
data is of critical importance to program 
designers. 

The network version of your 
software can be a real asset to its users 
if you implement it carefully, or it can 
cause more trouble than it is worth to 
an overworked or under-experienced 
administrator. It is important to test 
network software on the network it is 
destined for, in an environment com¬ 
parable to its target environment. Do 
not assume that what will run under 
Novell will run under Banyan or LAN 
Manager. Each network has its 
idiosyncrasies and the savings in tech 
support will far outweigh the extra time 
and expense required to test the 
software on each environment □ 
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David Hahn 



NetWare SQL APIs In Windows 


This article ties together three industry trends, namely client/server architec¬ 
ture, SQL, and Windows. The resulting Windows application can execute simple 
SQL statements and retrieve data from a NetWare SQL remote server. 

NetWare SQL And Windows 

NetWare SQL is an SQL relational database engine that runs on a NetWare 
server, also known as the host or server side. An application running on a 
workstation, also known as the client side, can access data managed by Net¬ 
Ware SQL through the NetWare SQL Requester (NSREQ), a TSR requester. NSREQ 
intercepts requests from the client application and transfers data between it 
and the host database engine. This scheme reflects the basic 
model of a client/server architecture. 

NSREQ v2.12a (or greater) is compatible With Microsoft Windows 
applications. Although NSREQ runs in real mode, a Windows ap¬ 
plication running in protected mode can access NSREQ through the 
DOS Protected Mode Interface (DPMI). The NetWare SQL package 
includes another requester, 


NSREQS.EXE, which is a smaller but 
equally functional version of NSREQ. 
NSREQS requires less memory by 
giving more of the processing respon¬ 
sibility to the host 

To make a Windows application 
capable of accessing a NetWare SQL 
host, you need only link UXQLCALL. LIB 
with the application's own objects, and 
put UXQLCALL.DLL in the search path. 
XQLCALLS.H contains the NetWare SQL 
API prototypes. The application then 
performs a series of steps to execute a 
SQL statement and retrieve data, each 
in the form of a NetWare SQL API. 


David Hahn is a software engineer in 
Engineering Services with Novell, Inc., in 
Austin, TX. He specializes in database 
testing and in test tool development 
You may contact him by mail at Novell 
at 5918 W. Courtyard Dr., Austin, TX 
48730. 
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Listing 1 (frontend.c) 

linclude “windows.h" 
linclude “frontend.h" 
linclude “xqlcalls.h" 

/* Main Window Process */ 

long FAR PASCAL MainWndProc(HWND,unsigned,WORD,LONG); 
BOOL FAR PASCAL SQLDlgProc (HWND,unsigned,WORD,LONG); 

void ExecSQL (void); 
int FetchRecords (void); 

char appName[] = “FRONTEND"; 

char msgS [80]; /* Message box text */ 

int status; /* Returned status of XQL call */ 


int PASCAL WinMain (HANDLE hlnstance, 

HANDLE hPrevInstance, 
LPSTR IpszCmdLine, 
int nCmdShow) 

{ 


WNDCLASS MainWndClass; 
MSG msg; 

HWND hMainWnd; 


if (IhPrevInstance) 

( 

MainWndClass.style 

MainWndClass.1pfnWndProc 
MainWndClass.cbClsExtra 
MainWndClass.cbWndExtra 
MainWndClass.hlnstance 
MainWndClass.hlcon 

MainWndClass.hCursor 

MainWndClass.hbrBackground 

MainWndClass.1pszMenuName 
MainWndClass.lpszClassName 


CS_HREDRAW | 

CS_VREDRAW; 

MainWndProc; 

0 ; 

0 ; 

hlnstance; 

Loadlcon (NULL, 
IDI_APPLICATI0N); 
LoadCursor (NULL, 
IDC_ARR0W); 
GetStockObject 

(WHITEJRUSH); 

NULL; 

appName; 


if (IRegisterClass (AMainWndClass)) 
return (FALSE); 

} 

arrowCursor = MainWndClass.hCursor; 
waitCursor = LoadCursor (NULL, IDC_WAIT); 


hMainWnd = CreateWindow (appName, 

“FE APP", 

WS_OVERLAPPEDWINDOW | WS_CLIPCHILDREN, 
GetSystemMetrics (SM_CXSCREEN) / 10, 
GetSystemMetrics (SM_CXSCREEN) / 10, 

3 * GetSystemMetrics (SM_CXSCREEN) / 4, 
3 * GetSystemMetrics (SMCXSCREEN) / 4, 
NULL, 

NULL, 

hlnstance, 

NULL); 


ShowWindow (hMainWnd, nCmdShow); 
UpdateWindow (hMainWnd); 

while (GetMessage (&msg, NULL, 0, 0)) 

( 

TranslateMessage (&msg); 
DispatchMessage (&msg); 

} 

return (msg.wParam); 

) 


NetWare SQL APIs 

NetWare SQL APIs are split into two groups: the XQL 
Manager and XQL Relational Primitives. I will discuss the 
simpler and higher level of the two, the XQL Manager. Simple 
data storage and retrieval with NetWare SQL can be per¬ 
formed with only seven XQL Manager APIs (Figure 1). Each API 
returns a zero if successful, a positive status if not successful, 
or sometimes a negative status indicating a specific successful 
action. All codes are fully described in the NetWare SQL 
manuals, which also describe the other ten XQL Manager APIs. 

To illustrate how a Windows application uses the seven 
essential APIs, I will follow an actual SQL statement as it is 
processed through the application. I will use the popular 

SELECT * FROM PATIENTS 

for my SQL statement. A flowchart showing the logical order¬ 
ing of the APIs appears in Figure 2. 

Logging In 

Before NetWare SQL will acknowledge my application’s 
presence, the application must establish a session with Net¬ 
Ware SQL using the XQLLogin API. Most NetWare SQL APIs re¬ 
quire that a session be established first. If you have estab¬ 
lished security on the database, XQLLogin takes username and 
password. Otherwise, you can pass NULLs in those variables. 
XQLLogin also requires the directories containing the data dic¬ 
tionary and the data files (NULLs if located in the same direc¬ 
tory as the application), and a NULL and a zero for future com¬ 
patibility. Assuming that I’m running my application in the 
same directory as the dictionary files and that I haven't taken 
security measures, my application would make the call 

username = (char) 0; 
password = (char) 0; 
ddPath = (char) 0; 
dataPath = (char) 0; 
reservel = (char) 0; 
reserve2 = 0; 

status = XQLLogin (username, 
password, 
ddpath, 
datapath, 
reservel, 
reserve2); 

Obtaining A Cursor 

Assuming XQLLogin returns a status of 0, I then request a 
cursor ID from NetWare SQL with the XQLCursor API. 
XQLCursor takes only one parameter, cursorlD. This API allo¬ 
cates internal resources and returns a cursor ID to reference 
those resources. Since the parameter must be passed by ref¬ 
erence, my application would use 

cursorlD = -1; 

status = XQLCursor (&cursorID); 
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Initializing cursorlD to -1 is a good practice, since the Net¬ 
Ware SQL Engine will return a cursor value of 0 for the first 
call, 1 for the next, and so on. If cursorlD remains -1, then it 
was not set correctly. 

Compiling The Statement 

Having performed the groundwork, I can compile my SQL 
statement with XQLCompile. Passed to XQLCompile is the 
cursorlD obtained from XQLCursor, the length of the SQL 
statement, and a pointer to the SQL statement text. 

strcpy (statement, "SELECT * FROM PATIENTS"); 
length = strlen (statement); 

status = XQLCompile (cursorlD, &length, statement); 

If the statement was complete, XQLCompile would imme¬ 
diately execute the statement and return the resulting status 
code. However, since I am performing a SELECT, XQLCompile 
does not execute the statement, but returns a zero status 
code. I must use XQLFetch to execute the SELECT and return 
the records. 

Fetching The Records 

XQLFetch takes a whopping seven parameters. First is 
cursorlD. Next I must indicate which record I want returned, 
and whether I want to use locking. Since this fetch is my first, 
I want to start with the first record and no locking. I place the 
option code 1, for retrieve-first-record, in the low byte of the 


Figure 1 

XQLLogin (LPBYTE ‘user, LPBYTE ‘password, 

LPBYTE *DDPath, LPBYTE ‘datapath, 

LPBYTE ‘reserved, WORD reserved) 

XQLCursor (LPWORD ‘cursorlD) 

XQLCompile (WORD cursorlD, LPWORD statementLen, 

LPBYTE statement) 

XQLFetch (WORD cursorlD, WORD option, LPWORD bufLen, 
LPBYTE ‘dataBuf, LPLONG count, 

WORD ASCIIFlag, WORD spacing) 

XQLFree (WORD cursorlD) 

XQLLogout (void) 

XQLStop (void) 

Seven XQL Manager API Function Prototypes 


second parameter, and the code 0, for no locking, in the high 
byte. Thus my second parameter is simply 1. For subsequent 
calls to XQLFetch I would use option 2 (fetch next record). The 
NetWare SQL manuals detail several more options. 

The next two parameters, dataBuf and bufLen, should 
contain the address and length, respectively, of the data buff¬ 
er in which NetWare SQL will store the returned record. You 
should allocate enough space to store at least one full record. 

Parameter five, count, should pass the number of records 
you want NetWare SQL to retrieve. It will return the number 
of records it was able to retrieve. 

The sixth parameter, ASCIIFlag, controls the formatting of 
the returned data. A value of 0 instructs NetWare SQL to 


Figure 2 
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Listing 1 

/*. - .*/ 

— Cont’d 

long FAR PASCAL MainWndProc (HWND hWnd, 

GetDlgltemText (hDlg, X IN WIN, (LPSTR) 

unsigned message, 

statement, MAXSTATELEN-1); 

WORD wParam, LONG IParam) 

SetCursor (waitCursor); 

{ 

ExecSQL (); 

static HANDLE hlnstance; 

SetCursor (arrowCursor); 

if (status < 0) /* Informative stat code */ 

switch (message) 

( 

{ 

sprintf (msgS, 

case WM CREATE : 

"Statement executed successfully"); 

hDC = GetDC (hWnd); 

SetDlgltemText (hDlg, X OUT WIN, msgS); 

SelectObject (hDC, GetStockObject 

(SYSTEM FIXED FONT)); 

) 

ReleaseDC (hWnd, hDC); 

else if (status > 0) /* Error! */ 

( 

sprintf (msgS, 

SetCursor (waitCursor); 

status = XQLLogin (userid, password, 

"Compile Error - status - %d“, status); 

ddpath, datapath. 

SetDlgltemText (hDlg, X OUT WIN, msgS); 

sReserved, iReserved); 

SetCursor (arrowCursor); 

) 

if (status) 

else /* Operation was SELECT */ 

{ 

buffer = (char *) Local Alloc 

1 

sprintf (msgS, 

"A login error occurred, status: %d", 

(LPTR, MAXSTATELEN); 

status); 

status = FetchRecords (); 

MessageBox (NULL, msgS, " ERROR ", 

SetDlgltemText (hDlg, X OUT WIN, ""); 

MB OK | MB ICONEXCLAMATION); 

) 

el se 

if (status) 

/ 

\ 

sprintf (msgS, 

{ 

“Fetch Error - status - %d“, status); 

hlnstance = ((LPCREATESTRUCT) 

SetDlgltemText (hDlg, X OUT WIN, msgS); 

1Param)->hlnstance; 
procAddr = MakeProcInstance 

) 

(SQLDlgProc, hlnstance); 

else 

DialogBox (hlnstance, '‘SQLBox”, 

{ 

hWnd, procAddr); 

hDC = GetDC (hDlg); 

FreeProcInstance (procAddr); 

SelectObject (hDC, GetStockObject 

XQLFree (cursorlD); 

(SYSTEM FIXED FONT)); 

XQLLogout (); 

ReleaseDC (hDlg, hDC); 

XQLStop (); 

SetDlgltemText (hDlg, X OUT WIN, 

} 

SendMessage (hWnd, WM CLOSE, 0, OL); 

buffer); 

} 

return 0; 

Local Free ((LOCALHANDLE) buffer); 

case WM_CL0SE : 

DestroyWindow (hWnd); 

) 

return 0; 

SetFocus (GetDlgltem (hDlg, X_IN_WIN)); 

case WM_DESTROY : 

PostQuitMessage (0); 

return (TRUE); 

return 0; 

case X CLEAR : 

SetDlgltemText (hDlg, X IN WIN, '"'); 

} 

SetDlgltemText (hDlg, X OUT WIN, ""); 

return (DefWindowProc (hWnd, message, 

SetFocus (GetDlgltem (hDlg, X IN WIN)); 

wParam, IParam)); 

) 

return (TRUE); 

case X END DLG: 

/*.*/ 

EndDialog (hDlg, 0); 

BOOL FAR PASCAL SQLDlgProc (HWND hDlg, 

return (TRUE); 

unsigned message, 

) 

WORD wParam, LONG IParam) 

default : 
break; 

) 

return (FALSE); 

) 

( 

switch (message) 

{ 

case WM_INITDIALOG : 

SetFocus (GetDlgltem (hDlg, X_IN_WIN) ); 
return (TRUE); 

case WM_COMMAND : 
switch (wParam) 

{ 

case X_SEND : 
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Listing 1 — Cont’d 


/* . 

void ExecSQL (void) 


if (cursorlD «■ -1) 

( 

status = XQLCursor ((LPWORD) &cursorID); 
if (status) 
return; 

) 

statlen = strlen (statement); 

status * XQLCompile (cursorlD, (LPWORD) 

&statlen, (LPBYTE) statement); 

return; 

) 


/*. 

int FetchRecords (void) 

( 

int option = 1; 
int ASCI I FIag = 1; 
int spacing = 2; 

int count; 
long recLen, recCount; 
int bufSize; 
char *p; 


bufSize = MAXBUFLEN; 
recCount * 10; 

status - XQLFetch (cursorlD, option, SbufSize, 
buffer, &recCount, 

ASCIIFlag, spacing); 

if (status > 0) /* Fetch was not successful */ 

{ 

Local Free ((LOCALHANDLE) buffer); 
return (status); 

} 

p ■ buffer; 

recLen * ‘(long *) p; /* Get length */ 

/* Hake buffer printable */ 

/ for (count = 0; count < recCount; count++) 

( 

(char) *p » (char) 13; 

(char) *(p+l) = (char) 10; 
p +■ (2 + recLen); 
recLen - ‘(long *) p; 

) 

return (0); 

) 


/* End of File */ 
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return data with no intervening spaces between fields. A 
value of 1 indicates that blanks should be stored between 
fields. The last valid value is 2, directing NetWare SQL to store 
binary zeros between fields. 

The last parameter, spacing, indicates the number of blank 
spaces or binary zeros that should be stored between fields. If 
you pass 0 in ASCIIFlag, then you should also pass 0 in spac¬ 
ing, since no spaces are placed between fields. For values of 1 
and 2 in ASCIIFlag, spacing can be set to a higher number. 

Putting all the parameters together, 1 have 


option = 1; 
bufLen = 512; 

dataBuf = (char *) malloc (512); 
count = 20; 

ASCIIFlag = 1; 
spacing = 1; 

status = XQLFetch (cursorlD, 
option, 

SbufLen, 

dataBuf, 

&count, 

ASCIIFlag, 

spacing); 


Listing 2 (frontend.h) 

linclude "windows.h" 


Listing 3 (frontend.rc) 

♦define X IN WIN 0x0601 


♦include "windows.h" 

♦define X OUT WIN 0x0602 
♦define X SEND 0x0603 


♦include "frontend.h" 

♦define X CLEAR 0x0604 

♦define X_END_DLG 0x0605 


SQLBox DIALOG DISCARDABLE L0AD0NCALL MOVEABLE 4, 31, 249, 171 

STYLE WS P0PUPWIND0W | WS CAPTION 

♦define MAXBUFLEN 1024 
♦define MAXSTATELEN 255 


CAPTION "FrontEnd" 

HMENU hMainMenu; 


BEGIN 

HDC hDC; 


CONTROL "" X IN WIN, "EDIT", WS CHILD | 

FARPROC procAddr; 


WS VISIBLE I WS BORDER | ES LEFT | ES AUTOVSCROLL | 

HCURS0R waitCursor; 


ES MULTILINE | WS TABST0P, 4, 7, 199, 47 

HCURS0R arrowCursor; 


CONTROL "" X OUT WIN, "EDIT", WS CHILD | 

/* ddpath and datapath should be 
changed to reflect the location 


WS_VISIBLE | WS_B0RDER | ES_LEFT | ES_MULTILINE, 

of the data dictionaries */ 


4, 63, 241, 103 

char ddpath [ ] = M c:\\ M ; 


CONTROL "SEND" X SEND, "BUTTON", WS CHILD | 

char datapath [ ] = "c:\\"; 


WS_VISIBLE | WSJABSTOP, 210, 8, 32, 12 

char userid [ ] * "\0"; 


CONTROL "Clear" X CLEAR, "BUTTON", WS CHILD | 

char password [ ] = "\0"; 


WS VISIBLE | WS TABSTOP, 210, 25, 32, 12 

char sReserved [ ] = M \0"; 
int iReserved = 0; 


CONTROL "Exit" X END DLG, "BUTTON", WS CHILD | 

char *buffer; 

char statement [255]; 


WS_VISIBLE 1 WSJABSTOP, 210, 42, 32, 12 

int cursorlD = -1; 
int statlen; 
int status; 


END 


Page 24 - Windows/DOS Developer's Journal 


December 1991 

















































Freeing The Cursor 

If the fetch operation was successful, I now have a pointer 
to either 512 bytes of records, or 20 complete records, 
whichever is smaller. Assuming I no longer wish to access Net¬ 
Ware SQL, I must free the resources I allocated by freeing my 
cursor. XQLFree performs this API, taking cursorlD as a 
parameter: 

status = XQLFree (cursorlD); 

Logging Out 

The application must log out of the database. XQLLogout 
terminates the XQL session without any parameters: 

status = XQLLogout (); 

XQLLogout will also release any cursor not released with 
XQLFree, though it is good practice to deallocate them ex¬ 
plicitly. Finally a call to XQLStop 

status = XQLStop (); 

releases other session-independent resources maintained for 
multiple Windows sessions and breaks the IPX/SPX connection 
with the NetWare SQL Engine. 

The Application 

FRONTEND is a simple Windows application that uses the 
seven essential NetWare SQL APIs. I compiled and linked it 
with Borland C++ v2.0, although I also could have used the 
Windows SDK and Microsoft C v6.0. Listing 1 contains the C 
source code, Listing 2 the header file, Listing 3 the resource 
file, Listing 4 the definition file, and Listing 5 the make file. 

FRONTEND logs into the database, accepts SQL statements 
from the keyboard, executes the necessary NetWare SQL 
Manager APIs, and returns either the status code of the opera¬ 
tion or the fetched records for a SELECT statement. Upon exit¬ 
ing the program, FRONTEND logs out of the database and 
breaks the connection. 

For the sake of simplicity, FRONTEND has arbitrary limits set 
on the statement size and returned record size. Adding scroll 
bars and corresponding code could increase both sizes. 

FRONTEND provides an excellent starting point for exploring 
NetWare SQL, Windows programming, and SQL in general. Fur¬ 
ther enhancements could also include the remaining ten Net¬ 
Ware SQL Manager APIs involving stored SQL statements, sub¬ 
stitution variables, data conversion, and more. A fully-featured 
database management system is only a few more lines of 
code away. □ 
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Listing 4 (frontend.def) 

NAME 

FRONTEND 


DESCRIPTION 

'NetWare SQL Application' 


EXETYPE 

WINDOWS 


STUB 

'WINSTUB.EXE' 


SEGMENTS 

FRONTEND TEXT MOVEABLE DISCARDABLE L0AD0NCALL 


TEXT MOVEABLE DISCARDABLE 

PRELOAD 

DATA 

MOVEABLE MULTIPLE PRELOAD 


CODE 

MOVEABLE DISCARDABLE 


HEAPSIZE 

1024 


STACKSIZE 

8192 


EXPORTS 

MainWndProc 

SQLDlgProc 




Listing 5 (frontend.mak) 

# Makefile (Borland C++) for FRONTEND program 

frontend 

.exe : frontend.obj frontend.res 

frontend.Ink 

tlink 

/Twe cOws frontend, frontend, frontend, cwins\ 


cs import wxqlcall, frontenc 

.def 

rc -ic 

:\bcpp\include frontend.rc 


frontend 

•obj : frontend.c frontend.h frontend.mak 

bcc -I 

c:\bcpp\include -W -c -ms frontend.c 

frontend 

■res : frontend.rc frontend.h 


rc -r 

-ic:\bcpp\include frontend.rc 



TCP/IP tor Windows 3 


Release 2.0 Now Shipping 

Software Development Kit and Applications* 

NEWT is the first TCP/IP package developed specifically (not 
converted from DOS) for Windows 3.0. NEWT-SDK takes full 
advantage of Windows' flexibility and multitasking capability. 
This software development kit offers the. programmer direct 
access to the Transport, Network, and Datalink (MAC) layers. 


□ Implemented as a DLL (no TSR) 

□ Multiple windows run multiple 
TCP/IP sessions concurrently 

□ TCP, UDP, ICMP, IP, and MAC 

□ Ethernet, Token Ring and FDDI 
O Berkeley 4.3BSD socket interface 

□ NDIS interface 

□ Concurrent LAN and SLIP 

□ Windows based set-up program 

□ Tracks and displays all network 
statistics 

□ Supports multiple network 
boards simultaneously 

□ Supports IP routing 

Only $500 


□ Three DLLs included: 
NEWT: TCP/IP stack 
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Networks 


Tuning A Lan Database 


Michael Rockwell 


Introduction 

Database applications, though particularly well suited for use on a LAN, are 
difficult to tune because of their widely varying data characteristics and 
processing needs. The factors that most directly affect the tuning requirements 
are the LAN’s access method, the application’s awareness of the LAN, the size of 
the data record to be processed, and the rate of transaction at the workstation. 

This article describes how each factor affects the performance of a database 
on a LAN and discusses which elements of the LAN should be tuned to improve 
performance based on the requirements of these factors. It also shows how to 
analyze LAN traffic patterns and how to tune a LAN on the basis of this analysis. 
The focus is on Token-Ring and CSMA/CD access method because they are the 
most widely used, but the methods discussed will work with other access 
methods as well as with non-database applications. 

The tuning of a LAN is an ongoing effort. As the LAN grows and as other 
applications are run on it the parameters will require adjustment and tradeoffs 
will have to be made. I hope that the information presented here will help you 
to make intelligent tuning decisions. 

LAN Basics/Terms 

A local area network (LAN) is defined as a high 
—i———— bandwidth data communications network that spans 

a limited geographical area - a few miles at most It 
allows users to share information and computer 
I resources, including mass data storage, backup 
_ facilities, software, printers, modems, 

and processors. 

1 Workstations (PCs) on a LAN are 
joined via some sort of media - copper 
wire, fiber optic cable, radio, or light 
waves. Typically, a LAN is connected by 
copper wire in the form of coaxial or 
twisted-pair wire. 

The communications media usually 
connects to a network interface card 
(NIC) in the workstation. The NIC con¬ 
tains hardware and software to support 
a particular media access method. The 
media access method defines the rules 
and format that will be used to trans¬ 
mit data over a network. Common 


Michael Rockwell is a data com¬ 
munications consultant for Computer 
Task Group, Inc He may be contacted 
by phone at (716) 888-3526 or by mail 
in care of Computer Task Group, Inc., 
800 Delaware Ave, Buffalo, NY 14209. 
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media access methods include Ethernet (CSMA/CD), Token-Ring, 
and Arcnet (see the sidebar for an in-depth discussion of how 
the CSMA/CD and Token-Ring access methods work). 

The final component of a LAN is the network operating 
system (NOS). The NOS works with the NIC and disk operating 
system (DOS) to make the network perform as transparently 
as possible and to provide functionality. The NOS makes the 
workstation think that a shared network resource is physically 
present in the workstation. 

Access to network resources is effected through redirec¬ 
tion, that is, by intercepting something headed in one direc¬ 
tion and sending it in another. In the case of a LAN, the NOS 
intercepts the commands from a workstation to a shared 
device on the network and sends them over the LAN to the 
workstation that physically owns the device. A workstation 
that shares its resources is usually referred to as a server, 
while a workstation that uses resources is referred to as a 
requester. 

Data packets are the unit of transmission used for com¬ 
municating data on most networks. Files and messages are 
broken into data packets as they are sent, then are reas¬ 
sembled at the other end to form the original file or message. 
A data packet has three sections: header, data, and trailer. The 
header includes an alert to signal “packet on the way,” the 
packet’s source address and destination address, and other 
preamble information required by the protocol. The data sec¬ 
tion contains the data being sent; its size varies depending on 
the network. The trailer section has an error-checking code 
known as the cycle redundancy check (CRC), which is a math¬ 
ematical calculation performed on the data before it is sent 
The receiving network interface card performs the same cal¬ 
culation on the data it received, then compares the result 
with the one sent. If the two match, then no error occurred 
during the transmission. 

The header and trailer add overhead to the process of ac¬ 
cessing the data. This overhead requires additional processing 
in order to restore the data to its original form. It is possible, 
however, to tune a LAN to reduce the overhead. 

Most NICs buffer data packets as they are received. Buffers 
are blocks of memory set aside so that the NIC can receive 
data packets even when the workstation is too busy to 
process the data immediately. Some NOS's allow for two sizes 
of buffers, large and small, to permit better utilization of buff¬ 
er memory. Typically, a workstation needs one transmit buffer 
and several receive buffers, because the burden of data flow 
is on the receiving workstation to accept the data packet and 
send a confirmation to the sending workstation. If the packet 
is not accepted, the sending workstation simply resends the 
data. Congestion at the receiving workstation (all buffers full) is 
the most common source of network performance problems 
in that it forces all packets to be resent. A sufficient number 
of receive buffers will eliminate this problem, but the tradeoff 
is a reduction in the amount of RAM available for application 
programs. The key here is to figure out how processor-inten¬ 
sive the application is. A highly processor-intensive application 
lets data sit in the receive buffers longer than a less proces¬ 
sor-intensive application, so more receive buffers are needed 
for processor-intensive applications. 



Access Method 

The access method used by the LAN has a great deal to do 
with how the LAN is tuned. CSMA/CD works best for sending 
large amounts of data infrequently. It handles large amounts 
of data well because it has low packet overhead and because 
the workstation owns the carrier until all its data is sent How¬ 
ever, performance deteriorates as the frequency of transac¬ 
tions increases because of collisions and a randomness in ac¬ 
cessing the media. Token-Ring, on the other hand, is best for 
managing large amounts of traffic from many users. This is 
because of Token-Ring’s built-in fairness rules. The worse case 
traffic scenarios on a Token-Ring can be predicted by multi¬ 
plying the token hold limit by the number of attached 
workstations, which is useful for capacity management pur¬ 
poses. Token-Ring packets have more overhead than CSMA/CD 
packets, but this does not affect throughput Data transmis¬ 
sion speeds are limited more by the NOS and the computer’s 
internal processing on the server and workstation than by the 
network media speed. 

LAN Applications 

LAN applications (for purposes of this discussion) are the 
programs that run on the local area network. These applica¬ 
tions can be classified as either LAN-ignorant, LAN-aware, or 
LAN-intrinsic. 
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LAN-Ignorant Applications 

A LAN-ignorant application is an application written for 
single use by a single person on a single computer. Such ap¬ 
plications can be run on a LAN but are unpredictable when 
used simultaneously by more than one user. Problems usually 
occur when two users are working on the same file at the 
same time. For example, if two users are running a word 
processor and editing the same document, the last version 
saved will overwrite all previous versions, thus losing the work 
of the user who saved the document first. Since the program 
was meant to be run on a standalone machine, it does not 
provide for concurrency control, that is, it has no way of track¬ 
ing or limiting access to documents. Such an application is said 
to be LAN-ignorant. 

LAN NOS vendors have recognized this problem and are 
now providing a means of restricting access to the program 
itself via the NOS so that only one person can be running the 
application at one time. This strategy, however, defeats the 
purpose of a LAN, especially if the application is heavily used. 
Instead, many application software developers are now writ¬ 
ing their applications to be LAN-aware. 

LAN-Aware Applications 

A LAN-aware application is a program that has concurrency 
controls such as file and record locking built in. Using the 
same word processor example, when the second user at¬ 
tempts to load the document, the operating system will in¬ 
form the program that the document is logged out by another 


user and access will be denied. This process is called file lock¬ 
ing because access to the entire file is restricted until the first 
user is finished. A variation used for database applications, is 
record locking. In a database, a user works with only one 
record at a time, so it is neither reasonable nor desirable to 
lock the entire file, instead only the record (section of the file) 
that is being acted upon is locked. 

Most LAN applications fall into this category. A major prob¬ 
lem with this method is that the entire database needs to be 
sent across the network so that its records can be queried 
and searched. Another problem is the volley of record locking 
and unlocking going on across the network. These shortcom¬ 
ings are solved by the latest technique in LAN software 
design, called LAN-intrinsic. 

LAN-Intrinsic Applications 

A LAN-intrinsic application shares the processing power of 
several machines, through a client-server relationship. In this 
approach, the application software is divided into pieces, one 
piece being the server, which does the back-end processing, 
and the other piece being the client, which formulates re¬ 
quests for data and displays the results. 

A database server provides a good example of how client- 
server works. In a database server application there are two 
pieces - the front end and the back end. The front end is 
responsible for formulating requests and presenting formatted 
data; the back end is responsible for searching databases, con¬ 
currency control, and security. At the front end, users can do 
everything they could do with a LAN-aware or LAN-ignorant 
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Media Access Methods 

Carrier Sensing Multiple Access/ 
Collision Detection (CSMA/CD) 

Ethernet uses a Carrier Sensing Multiple Access Col¬ 
lision Detection (CSMA/CD) media access method, that 
gives every workstation on the network has the same 
media access rights. To send a packet of data to send, 
a workstation first checks the media to see if anyone 
else is transmitting. If not, the workstation starts trans¬ 
mitting its packet, via a signal called a carrier. 

The one problem with this access method is that, 
because of propagation delay (a slight delay between 
the time the packet is sent and the time it reaches the 
ends of the network), it is possible for two worksta¬ 
tions to transmit packets simultaneously onto the 
media. For this reason, collision detection has been 
built into the CSMA/CD standard. The network interface 
card (NIC) monitors the media to see that the bytes 
being received are the same as those being trans¬ 
mitted. If the NIC detects a collision, both cards stop 
transmitting and set a random delay before trying to 
retransmit. 

Token Passing Ring 

Token-Ring uses a token passing method of media 
access. A token is a bit pattern in the data packets 
header that shows use. when the media is not in use, 
a data packet with the token free is passed around the 
ring to each attached workstation. To ensure fair and 
orderly media access, only one workstation can have 
the token at a time. To access the media (ring), the 
workstation must request the token and then wait for 
its turn to transmit. After receiving the token, the 
workstation copies its data packet onto the ring and 
then each downstream workstation regenerates the 
packet onto the next workstation. When the packet 
reaches the addressed workstation, the workstation 
copies the packet into its buffer and sets the receipt 
bit as it regenerates the packet On receiving this con¬ 
firmation, the sending workstation releases the token 
so that it can be claimed by the net requester. The 
sending workstation must release the token after each 
packet and must then re-request the token to con¬ 
tinue sending data. 

The token passing method ensures that everyone 
gets equal time on the ring, and, while it may at first 
seem to be very time-consuming, in actuality it is quite 
fast. As network traffic changes, so does the pace of all 
other traffic. In contrast, CSMA/CD traffic is sporadic, 
depending on the availability of the carrier. However, 
when a CSMA/CD workstation does get the carrier, all 
the data is sent at one time. The decision as to which 
access method is best depends on your network traffic 
patterns. □ 
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program. The difference is in how the processing and network 
traffic is handled. In a LAN-aware or LAN-ignorant program, the 
entire program runs on the user's PC. When a user makes a 
query against a database, the entire data file is sent over the 
network to the user's computer. The program can then select 
out the records it needs and discard the rest 

In contrast, a LAN-intrinsic program sends only the front 
end of the software over the network for execution on the 
local workstation. When the user enters a query, the query is 
sent over the network to the database server. The server then 
selects all the records that match the query and sends them 
back to the front end for display to the user. From this ex¬ 
ample it can be seen that the traffic on the network would be 
reduced tremendously, because the minimum amount of in¬ 
formation traverses the network. Another benefit is data 
security. Since only the requested information travels over the 
network to the user's workstation, there is no possibility of 
intercepting or receiving information other than that re¬ 
quested. Finally, concurrency control is improved because it is 
enforced only on and by the server, eliminating the volley of 
locking and unlocking records across the network. 

Tuning LAN Applications 

Eliminating LAN-ignorant applications as simply un-suitable 
for use on a LAN leaves us with tuning issues for LAN-aware 
and LAN-intrinsic applications. The first of these to be con¬ 
sidered is buffer allocation. 

For a LAN-aware application, many large buffers must be 
set aside on the workstation to handle all the data being 
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shipped to the workstation (remember that the entire 
database must be sent over the LAN to the workstation). The 
server will also need a good number of small buffers to hand¬ 
le the volley of file and record locking requests. 

For a LAN-intrinsic application, the buffering requirements 
are much less because minimal traffic is traversing the net¬ 
work. The server needs sufficient small buffers to receive the 
queries when they come in, and the workstation needs suffi¬ 
cient buffers to receive the records returned from the query. If 
single records are queried, then small buffers about the size of 
the data record will do. If many records are returned, then 
sufficient large buffers should be allocated to capture the data 
as it is returned. 

Data Packet Size 

In determining the correct size for the LAN's data packet 
the first factor to be considered is the size of the data records. 
The ideal data packet size would exactly match the size of the 
data record. This, however, is not possible, since different 
databases have different record sizes and it is very unlikely 
that the LAN will be accessing only one database. In addition, 
the degree of flexibility allowed in adjusting packet sizes is 
determined by the network operating system and the media 
access method. Still, sizing the data packet to the size of the 
largest frequently used data record can greatly improve per¬ 
formance. A good LAN analyzer can provide feedback on the 
frequency of various sized packets on the network; by 
monitoring and adjusting accordingly, it should be possible to 
find an optimal size for your LAN’s data packet. 

A note of caution: if you adjust the size of the data packet, 
be sure to adjust both the send and receive buffer sizes so 
that they match. If the send buffer is larger than the receive 
buffer, the packet will be truncated and cause the CRC to fail. 
The data will then continually be resent and fail again in an 
infinite traffic loop. 

Transaction Frequency 

The frequency of transactions should also be used in deter¬ 
mining how much buffering will be required. The more fre¬ 
quent the transactions, the more receive buffers will be re¬ 
quired on both the requester and server. 

If you expert network utilization to exceed 60 percent for 
substantial periods of time, you may want to consider Token- 
Ring over CSMA/CD (Ethernet) because Token-Ring provides 
equal access to everyone. On a busy network, Token-Ring ses¬ 
sions are paced, while CSMA/CD sessions are sporadic, depend¬ 
ing on random chance for getting a free carrier. In addition, 
CSMA/CD's performance decreases as the frequency of transac¬ 
tions increases due to collisions. 

Summary 

The key to successfully tuning a LAN is to know as much 
as possible about how the LAN’s applications behave - how 
they interact with the LAN, the frequency of transactions, and 
the size of the data records. The process is ongoing; as new 
applications are added, the dynamics will change and retuning 
will be necessary. For reference and tracking purposes, it’s a 
good idea to keep a log of all changes and to monitor closely 
the statistics and logging information the network operating 
system provides. □ 
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A Windows 

NotifyBoxf) Function 

William Smith 


The MessageBox() function in Windows is a very handy and powerful func¬ 
tion. Using it allows one to create a simple 'one line’ Windows program. An 
example of this minimum Windows program is shown in Listing 1. 

Unfortunately, the MessageBox() function has a major drawback. Since it is a 
really a modal dialog box, everything stops until the user satisfies the dialog. 
The program that calls the MessageBox() function must wait for user input And 
as soon as the user satisfies the dialog the MessageBoxf) is destroyed and 
removed from the display. 

I needed a way to notify the user that the program was doing something 
that may take a long time. I needed to have the message displayed while the 
program was doing something. The MessageBox() function does not provide for 
this type of behavior. 

Sure, you replace the standard cursor with the hour glass cursor to tell the 
user to wait But I wanted to explain to the user that the program was present¬ 
ly doing something and I wanted to be able to describe what the program was 
doing. 

Out of need was born the NotifyBoxf) function. This function behaves very 
much like the Windows MessageBoxf) function, but with some significant dif¬ 
ferences. 



The NotifyBoxf) function is not a dialog box and requires no user 
input. There are no push buttons or controls that the user interacts 
with. The NotifyBoxf) function returns immediately, not after user 
input like the MessageBoxf) function. This allows the program to con¬ 
tinue on and do something significant - not just wait around for user 
input The lack of response to user action results in another major 
difference between the NotifyBoxf) and MessageBoxf) functions;. This 
difference is that the NotifyBoxf) function must be called again to 
remove it from the display. This is usually done after the long process 
is over. 


William Smith is engineering manager for Montana Software. You may contact him by 
mail at P.O. Box 663, Bozeman, MT 59771-0663 or by phone at (406) 586-2984. 
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Listing 1 (minimum.c) 

#inc1ude <windows.h> 

int PASCAL WinMain( HANDLE hlnstance, HANDLE hPrev- 
Instance, 

LPSTR IpszCmdLine, int nCmdShow ) 

{ 

MessageBox( NULL, "This is a simple “ 

"one line Windows program", 

"Simple Window Program", 

MB_0K | MB_ICONEXCLAMTION ); 
return( 0 ); 

} 

/* End of File */ 


The parameters passed to the NotifyBox 0 function are 
very similar to the Windows MessageBoxO function. The first 
three parameters are identical to the MessageBox() 
parameters. The first parameter is the parent window handle. 
This value can be NULL, but care should be provided when 
using the GetFocus() function to obtain a window handle for 
this parameter. The second parameter is a pointer to a string 
to be printed within the box. The third parameter is a pointer 
to a string to be printed as the window caption. The fourth 
parameter is different than the MessageBoxO function. In the 
case of the MessageBoxO function, the fourth parameter com¬ 
municates what type of control buttons and icon to display. 


Listing 2 (ntfy_box.c) 

/★★★*★**★******★★★******★*****★**★★★**★★★*★★★★**★★★**★★★★★* 

y********************************************************** 

File Name: NTFY BOX.C 

Name: NotifyBox 

Expanded Name: Notify Box 

Parameters: hWndParent - handle of parent window 

Description: Library of functions for displaying 

lpText - text to display in notify box 

a notification box or window. An 

lpCaption - caption text for notify box 

important requirment to use these 

Return: zero if error 

functions is too export the window 

nonzero if notify box is created or destroyed 

callback function NotifyBoxProc. 

successfully 

This function name must be added to 

Description: Creates and displays a notfiy box with the 

the EXPORTS section of the linker 

specified text and caption. The notify box 

definition file. 

is displayed in the center of the parent 

Program List: 

window. If a notify box already exists, the 

Global Function List: NotifyBox 

previous notify box is destroyed. 

NotifyBoxCreate 

★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★**************************y 

NotifyBoxDestroy 

int FAR NotifyBox( HWND hWndParent, LPSTR lpText, 

NotifyBoxProc 

LPSTR lpCaption, HANDLE hlnstanceParent ) 

Static Function List: get num notify text lines 

{ 

Local Macro List: NOTIFY BOX WIDTH 


NOTIFY BOX MAX NUM LINES 

int status = TRUE; 

NOTIFY BOX WND CLASS NAME 


Global Data: 

static HWND 1 hWndNotify = NULL; 

Static Data: g lpText 


Portability: MS Windows, Any memory model. 

if ( 1 hWndNotify == NULL ) 

Any windows compatable C Compiler 

{ 

★★*★**★***********★★*★★★*★★★*★**★**★★★★**★**★****★★*★*★★★★ J 


/* MS Windows */ 

l_hWndNotify = NotifyBoxCreate( hWndParent, 
lpText, lpCaption, hlnstanceParent ); 

linclude <windows.h> 


/* Own */ 

if ( 1 hWndNotify == NULL ) 

{ 

#include <ntfy_box.h> 

status = FALSE; 

} 

Idefine NOTIFY BOX WIDTH 40 

Idefine NOTIFY BOX MAX NUM LINES 20 

} /* if 1 hWndNotify */ 

Idefine N0TIFY_B0X_WND_CLASS_NAME "NotifyWndClassName" 

else 

{ 

/* Prototype for window proc callback funci ton */ 

LONG FAR PASCAL NotifyBoxProc ( HWND hWnd, 

status = NotifyBoxDestroy ( 1 hWndNotify ); 

unsigned int iMessage, WORD wParam, 


LONG IParam ); 

if ( status == TRUE ) 

{ 

1 hWndNotify = NULL; 

/* Prototypes for static functions */ 

static int NEAR get num notify text 1ines ( LPSTR lpText, 

} 

int Width ); 



} /* else */ 

/* Modual level global variables */ 


static LPSTR g_lpText; 

return ( status ); 

/* Multi modual global variables */ 

) /* function NotifyBox */ 

extern HANDLE G_hlnstance; 
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Listing 2 

— Cont’d 

/********************************************************** 

TEXTMETRIC TextMetrics; 

Name: NotifyBoxCreate 


Parameters: hWndParent - handle of parent window 

WNDCLASS WndClass; 

lpText - text to display in notify box 


lpCaption - caption text for notify box 

if ( hWndParent == NULL ) 

Return: handle of notify box window (NULL if error) 

f 

Description: Creates and displays a notfiy box with the 


specified text and caption. The notify box 

/* Check for a valid instance handle */ 

is displayed in the center of the parent 

if ( hlnstanceParent == NULL ) 

window. 

( 

★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★Ik******************** J 

MessageBox( hWndParent, 

HWND FAR NotifyBoxCreatef HWND hWndParent, LPSTR lpText, 

"Invalid parent instance handle.\n" 

LPSTR lpCaption, HANDLE hlnstanceParent ) 

"Unable to create NotifyBox.", 

{ 

NULL, 

MB OK | MB ICONEXCLAMATION ); 

BOOL NullWndParentFlag = FALSE: 

return ( FALSE ); 

} /* if hlnstanceParent "j/ 

HDC hDc; 



hWndParent » GetDesktopWindow(); 

HWND hWndNotify; 

NullWndParentFlag « TRUE; 

RECT Rect; 

} /* if hWndParent */ 

else 

short int 

{ 

TextHeight, 

hlnstanceParent = 

TextWidth, 

GetWindowWord( hWndParent, 

WindowWidth, 

GWW HINSTANCE ); 

NumberOfLines, 

) /* else */ 

WindowHeight, 

WindowXPos, 

WindowYPos; 
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Listing 2 

— Cont’d 

/* Create the window */ 

/* Register the window class 

hWndNotify * CreateWindow( 

** Note registering is no big 

NOTIFY BOX WND CUSS NAME, 

** deal - RegisterClass() 

lpCaption, 

** just fails. */ 

WS OVERLAPPED | WS BORDER, 

if ( NullWndParentFlag == TRUE ) 

WindowXPos, 

{ 

WindowYPos, 

WndClass.style 1 0; 

WindowWidth, 

} 

WindowHeight, 

el se 

hWndParent, 

{ 

NULL, 

WndClass.style = CS PARENTDC; 

hlnstanceParent, 

} 

WndClass.lpfnWndProc = NotifyBoxProc; 

NULL ); 

WndClass.cbClsExtra = 0; 

if ( hWndNotify ! = NULL ) 

WndClass.cbWndExtra = 0; 

WndClass.hlnstance * hlnstanceParent; 

f 

WndClass.hlcon = LoadIcon( NULL, IDI_APPLICATION ); 
WndClass.hCursor « LoadCursor( NULL, IDC ARROW ); 

hDc = GetDC( hWndNotify ); 

WndClass.hbrBackground = COLOR WINDOW + 1; 

/* Set the colors of the text. */ 

WndClass.IpszMenuName » NULL; 

SetTextColor( hDc, 

WndClass.IpszClassName = NOTIFY BOX WND CLASS NAME; 

GetSysColor( COLOR WINDOWTEXT ) ); 

RegisterClass( &WndClass ); 

/* Calculate the required size of the window */ 

SetBkColor( hDc, 

GetSysColor( C0L0R_WIND0W ) ); 

if ( hWndParent == NULL ) 

/* Copy text pointer into static data 

{ 

** to pass it into the window proc */ 

/* If there is no parent window use the windows 
** desktop */ 

g_lpText * lpText; 

hWndParent = GetDesktopWindowf); 

/* Display and paint the window */ 

} 

ShowWindow( hWndNotify, SW SHOW ); 

hDc = GetDC( hWndParent ); 

GetTextMetrics( hDc, &TextMetrics ); 

UpdateWindow( hWndNotify ); 

TextHeight * TextMetrics.tmHeight + 

TextMetrics.tmExternalLeading; 

ReleaseDC( hWndNotify, hDc ); 

TextWidth = TextMetrics.tmAveCharWidth; 

WindowWidth = TextWidth * ( NOTIFY BOX WIDTH + 2 ); 

} /* if hWndNotify */ 

WindowWidth += 2 * GetSystemMetrics( SM_CXBORDER ); 

NumberOfLines = get num notify text 1ines( lpText, 

return ( hWndNotify ); 

NOTIFY_B0X_WIDTH ); 

WindowHeight = ( NumberOfLines + 2 ) * TextHeight; 
WindowHeight +* GetSystemMetrics( SM CYCAPTION ) + 

} /* function NotifyBoxCreate */ 

2 * GetSystemMetrics( SM CYBORDER ); 

J ************************************★*****★**★★*★*★*★**★★* 

ReleaseDC( hWndParent, hDc ); 

Name: NotifyBoxDestroy 

Parameters: hWndNotify - handle of notify box window to 

/* Calculate the location of the window */ 

destroy 

GetWindowRect( hWndParent, &Rect ); 

Return: nonzero - notify box window was NULL or 
successfully destroyed 

/* Calculate X position */ 

zero - notify box was not destroyed 

WindowXPos * Rect.left + 

Description: Removes a notify box window from the display. 

( Rect.right - Rect.left ) / 2; 

★ ★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★ft***************** j 

WindowXPos -= WindowWidth / 2; 

BOOL FAR NotifyBoxDestroy( HWND hWndNotify ) 

if ( WindowXPos < 0 ) 

{ 

l 

WindowXPos = 0; 

} 

if ( hWndNotify != NULL ) 

{ 

return ( DestroyWindow( hWndNotify ) ); 

/* Calculate Y position */ 

WindowYPos * Rect.top + 

} 

( Rect.bottom - Rect.top ) / 2; 

WindowYPos -= WindowHeight / 2; 

return ( TRUE ); 

if ( WindowYPos < 0 ) 

{ 

WindowYPos = 0; 

} 

if ( NullWndParentFlag == TRUE ) 

f 

hWndParent = NULL; 

} 

) /* function NotifyBoxDestroy */ 
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Bsupport® for Btrieve 


Listing 2 — Cont’d 


/********************************************************** 

Name: NotfifyBoxProc 
Parameters: hWndNotify 
Return: 

Description: Windows callback function. 

**********************************************************y 

LONG FAR PASCAL NotifyBoxProc( HWND hWnd, 
unsigned int iMessage, WORD wParam, 

LONG IParam ) 


if ( iMessage == WM_PAINT ) 

{ 

BOOL FinishedFlag = FALSE; 
int 

Char, 

Line; 

char Buffer[NOTIFY_BOX_WIDTH + 1]; 

LPSTR lpCurrent; 

PAINTSTRUCT PaintStruct; 

TEXTMETRIC TextMetrics; 

lpCurrent = g_lpText; 

BeginPaint( hWnd, &PaintStruct ); 

GetTextMetrics( PaintStruct.hdc, &TextMetrics ); 

/* Set the colors of the text to defaults. */ 
SetTextColor( PaintStruct.hdc, 

GetSysColor( C0L0R_WIND0WTEXT ) ); 
SetBkColor( PaintStruct.hdc, 

GetSysColor( COLOR_WINDOW ] ); 

/* Print out the text line by line */ 
for ( Line = 0; Line < NOTIFY_BOX_MAX_NUM_LINES; 
Line++ ) 

{ 

for ( Char = 0; Char < N0TIFY_B0X_WIDTH; 
Char++ ) 

{ 

if ( ( lpCurrent [Char] == 1 \n 1 ) || 

( lpCurrent[Char] == 1 \0' ) ) 

( 

Buffer[Char] = ' \0 1 ; 

if ( lpCurrent [Char] ‘ \0 1 ] 

{ 

/* Hit end of string */ 
FinishedFlag = TRUE; 

} 

lpCurrent = &lpCurrent[Char + 1]; 
break; 

} 
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XSUPPORT™ FOR NETWARE SQL 


Database Administration tool for 
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Listing 2 — Cont’d 


Buffer[Char] = lpCurrentfChar]; 

} /* for Char */ 

if ( Char == NOTIFY_BOX_WIDTH ) 

{ 

/* Do word wrap */ 

for ( ; Char >= 0; Char- ) 

{ 

if ( lpCurrent[Char] == ' 1 ) 

{ 

BufferfChar] = '\0'; 
lpCurrent = 

SlpCurrent[Char + 1]; 

break; 

} /* if lpCurrent */ 

} /* for */ 

} /* if Char */ 

if ( Char ■« -1 ) 

{ 

/* Failure could not word wrap */ 
return ( 0L ); 

} 

else 

{ 

int Row; 

/* Print out the text */ 

Row ■ ( Line + 1 ) * 

( TextMetrics.tmHeight + 
TextMetrics.tmExternalLeading ); 

TextOut( PaintStruct.hdc, 

2 * TextMetrics.tmAveCharWidth, 
Row, Buffer, 

(int)lstrlen( Buffer ) ); 

} /* else */ 

if ( FinishedFlag ■* TRUE ) 

{ 

break; 

} 

} /* for Line */ 

return ( OL ); 

} /* if iMessage */ 

return ( DefWindowProc( hWnd, iMessage, wParam, 
IParam ) ); 

} /* function NotifyBoxProc */ 


Name: get_num_notify_text_lines 
Parameters: lpText - text to process 

Width - maximum number of characters in a line 
Return: The number of lines or -1 if error. 
Description: Does simple word wrap of text and calculates 
the number of lines that fit in a window of 
specified width in characters. 

********************************************************** j 

static int NEAR get_num_notify_text_lines( LPSTR lpText, 
int Width ) 


LPSTR lpCurrent; 
int 

Char, 

Line; 

if ( ( lpText == NULL ) || ( ‘lpText — '\0' ) ) 

{ 

/* Bad input string */ 
return ( 0 ); 

} 

lpCurrent = lpText; 

for ( Line = 0; Line < N0TIFY_B0X_MAX_NUM_LINES; 
Line++ ) 

{ 

for ( Char * 0; Char < Width; Cham ) 

{ 

if ( lpCurrentfChar] == '\0* ) 

{ 

/* Hit the end of the string */ 
return ( Line + 1 ); 

} 

if ( lpCurrentfChar] ■« '\n' ) 

{ 

/* Hit a new line */ 

lpCurrent = SlpCurrentfChar + 1]; 

break; 

} 

} /* for Char */ 

if ( Char == Width ) 

{ 

/* Exceeded the maximum width 
** search backwards for a space. */ 
for ( ; Char >» 0; Char- ) 

{ 

if ( lpCurrentfChar] == ' ' ) 

{ 

lpCurrent * SlpCurrentfChar + 1]; 
break; 

} 

) 

if ( Char == -1 ) 

f 

/* Failure - no space found */ 
return ( -1 ); 

} 

) /* if Char */ 

) /* for Line */ 

return ( Line ); 

} /* function get_num_notify_text_lines */ 

/* End of File */ 
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For the NotifyBox() function the fourth 
parameter is the instance handle for 
the application. This parameter is not 
needed as long as a valid parent win¬ 
dow handle is provided. The instance 
handle is obtained from the window 
handle by using the function Get- 
UindowUord(). This is why using the 
GetFocus() function to obtain a win¬ 
dow handle is dangerous. If a parent 
window handle is used that is actually 
a handle to a window in another ap¬ 
plication, the instance handle obtained 
is for another application. This situation 
will generate a UAE (Unrecoverable Ap¬ 
plication Error) when calling Create- 
Uindowf). If both the parent window 
handle and the instance handle are 
NULL, the NotifyBox() function fails. 

The NotifyBox() function is actually 
implemented with five functions. Listing 
2 contains the C code to these func¬ 
tions. Listing 3 contains the include file 
associated with these functions. The 
NotifyBox() function is just a simple 
shell that calls NotifyBoxCreate() and 
NotifyBoxDestroy() based upon the 
value of the static variable g_hWnd- 


Notify that keeps track of the handle 
of the notify box window handle. When 
NotifyBox() is called the first time 
g_hUndNotify is NULL so NotifyBox() 
calls NotifyBoxCreate(). The second 
time NotifyBoxf) is called, g_hUnd- 
Notify contains a valid window handle. 
In this situation, NotifyBox() calls 
NotifyBoxDestroyO which removes 
the notify box window from the display. 
This behavior limits an application to 
have only one notify box displayed at a 
time. If the need ever arises (I did not 
encounter it), one could call NotifyBox- 
Create() and NotifyBoxDestroyO 
directly. This is why I did not declare 
these functions as static. When using 
NotifyBoxCreate() and NotifyBox¬ 
DestroyO the programmer must keep 
track and manage the window handles 
that are returned by NotifyBox- 
Create() and passed as a parameter to 
No tifyBoxDestroy (). 

The other two functions are the 
Windows callback function for the 
notify window and a static function that 
does some simple word wrap calcula¬ 
tions to determine the number of lines 


Listing 3 (ntfy_box.h) 


/********************************************************** 
File Name: NTFY_B0X.H 
Expanded Name: Notify Box 
Description: Include file for NTFY_B0X.C 
Program List: 

Global Function List: 

Static Function List: 

Local Macro List: 

Global Data: 

Static Data: 

Portability: MS Windows C Compilers 
********************************************************** ^ 
#if !defined( NTFY_BOX_DEFINED ) 

Idefine NTFY_BOX_DEFINED 

int FAR NotifyBoxf HWND hWndParent, LPSTR lpText, 

LPSTR IpCaption, HANDLE hlnstanceParent ); 

HWND FAR NotifyBoxCreate( HWND hWndParent, 

LPSTR lpText, LPSTR IpCaption, 

HANDLE hlnstanceParent ); 

BOOL FAR NotifyBoxDestroy( HWND hWndNotify ); 

#endif 

/* End of File */ 
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If You Program 

in C, C++, Basic, Fortran, Cobol, 
Pascal, dBase, 


HI-SCREENPro II 

is your user interface solution 



With HI-SCREEN Pro II, you can design modern 
text and graphic user interfaces in a snap: 


► Design interface objects using interactive 
editors. Generate all windows, icons, 
menus, and data entry screens in a 
WYSIWYG fashion. 

>- Test all objects directly under the editors, 
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dialog boxes. 

> Manage objects from your program using a 
set of versatile and powerful functions. 


Hercules, CGA, EGA, VGA, 25/30/43/50 line 
modes (auto-detect) • Full mouse support & 
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hypertext effects, direct access to other editors 
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mode under the editor • Automatic context- 
sensitive help systems • Automatic scrolling 
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shadowing effects • Combine text and graphics • 
Capture any text and graphic screens • Flexible 
input management: field-by-field or full-screen, 
interrupt input before or after field, run parallel 
task, check current field, etc. • Automatic menu 
systems: pull-down, horizontal, vertical • Link 
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Only $395 • No royalties • Call for Windows 3 and 
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THE FAST, FLEXIBLE 
EASY TO USE GUI 

TEGL WINDOWS TOOLKITII 
The TEGL Windows Toolkit II is really 
three toolkits in one: a graphics inter¬ 
face, a memory manager and a window 
manager. Together they provide a pro¬ 
gramming environment. With the tools 
you get you can build a true event driven 
GUI for your DOS application. 


OUTSTANDING MATURES 


You get all these features and 
more for only $99: 

Adds as little as 100 K to the size of an 
application. 

Virtual memory management using 
EMS hard disk and handles. 

Extensive keyboard, mouse and timer 
event hooks. 

An icon editor to design and edit your own 
icons. 

World coordinates make it easier to fit 
data to the screen. 

TEGL graphics interface, a virtual plug¬ 
in replacement for BGI, but much faster 
and with special routines for windowing. 
40+ bit mapped fonts, some fonts support 
the complete IBM character set. 

Font editor to create fonts up to 100 x 100 
pixels. 

Dialogue management for easy data 
entry, pick lists, and messaging. 

Turbo Pascal objects and Turbo C++ 
class library. 

CGA, Hercules, EGA ,VGA and SVGA 
support in 2, 16 and 256 colors. 

Pascal version supports Turbo Pascal/ 
Quick Pascal. The C version supports 
Turbo C/C++, Quick C, Microsoft C and 
WATCOM C. 


WINDOW ROUTINES 


Fast scrolling in any direction, stan¬ 
dard character I/O, local menus, re- 
sizeable, scroll bars, headers, graphics 
clipping, CRT windows. 

The Complete Games Toolkit II 
Includes the TEGL Windows Toolkit plus com¬ 
plete source code for five games. The games are 
great examples of the use of the toolkit. Even in¬ 
cludes an electronic deck of cards to create your 
own card games. 


EXTRA BENEFITS 


No Royalties - Source Code Included 
30-day Money Back Guarantee 

Order today! (60*4)669-2577 

Fax (604)688-9530 

Visa/Mastercard/Cheque/Money Order 
TEGL Windows Toolkit II Release 2.0 
Pascal $99 C $99 

Complete Games Toolkit $139 
Shippings Handling $10 
Shipping outside Canada & U.S.A. $15 
Canadian residents add 7% GST 

TEGL SYSTEMS CORPORATION 
780-789 West Pender Street, Vancouver 
British Columbia, Canada Y6C 1H2 


of text The number of lines of text are 
needed to size the notify box window. 
The callback function NotifyBoxProc 
must be exported so Windows can call 
this function. Consequently, do not for¬ 


get to include this function name in the 
EXPORTS section of the linker definition 
file. 

Listing 4 is a demonstration program 
for the NotifyBox () function. □ 


Listing 4 (nbx_demo.c) 


^********************************************************** 
File Name: NBX_DEM0.C 
Expanded Name: Notify Box Demo 
Description: Demo program for NotifyBox function. 

This program demonstrates the windows 
MessageBox function and a similar 
NotifyBox function. Both are 
demonstrated with a very simple 
program that does not even register a 
main window! 


Program List: NBX_TEST.C NTFY_B0X.C 
Global Function List: WinMain 
Static Function List: 

Local Macro List: 

Global Data: 

Static Data: 

Portability: MS Windows, Any memory model, 

Any windows compatable C Compiler 

******************★********★*★★★★★*★**★********★**********j 


/* MS Windows */ 
linclude <windows.h> 

/* Types and prototypes */ 

#include <ntfy_box.h> 

int PASCAL WinMain! HANDLE hlnstance, HANDLE hPrevInstance, 
LPSTR IpszCmdLine, int nCmdShow ) 

f 

LONG i; 

/* Prompt user to start */ 

MessageBox( NULL, "Demonstration of NotifyBox " 
"function.\nHit Enter to begin a long " 

"process", "MessageBox", MB_0K ); 

/* Create Notify Box */ 

NotifyBox( NULL, "Doing a long process - looping " 
"10,000,000 (ten million) times!\n\n" 

"Please Wait...", "NotifyBox", 
hlnstance ); 

/* Do a long process */ 

for ( i = 0; i < 10000000; i++ ); 

/* Destroy Notify Box */ 

NotifyBoxf NULL, NULL, NULL, NULL ); 

/* Prompt user to exit program */ 

MessageBox! NULL, "Long process is over - NotifyBox " 
"has been destroyed.\nHit Enter to exit", 
"MessageBox", MB_0K ); 

return ( 0 ); 

} /* WinMain */ 

/* End of File */ 
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Writing For The PC Speaker 


Robert Bybee 


The IBM-PC speaker interface was originally designed to play only simple 
tones. Using an interesting software technique, applications can now produce 
reasonably high-quality voice and music through the PC speaker. Some com- 
mercially-available programs (mostly games) already take advantage of this 
method. Now your programs can do the same. 

Physics Review 

A speaker produces sound by moving air back and forth many times per 
second. The PC speaker interface consists of some digital hardware, driving an 
amplifier which moves the speaker’s cardboard cone. To produce a tone of, say, 
262 Hertz (middle C on a piano), the interface must move the speaker back and 
forth 262 times per second. 

The PC Implementation 

The PC uses two different methods to move the speaker. One of the timers 
on the motherboard (timer two in the 8253 chip, or its equivalent) can be 
programmed to generate a square wave of various frequencies. Setting bit zero 
of output port 61H to 1 sends the square wave to the speaker. Most programs, 
including the BIOS, use this method to generate a “beep” tone. 


Robert Bybee is Senior Electrical Engineer at Scientific Games, Atlanta Georgia, 
where he is involved with hardware and software design of point-of-sale ter¬ 
minals used in state lottery systems. He was previously with Chromatics, a 
manufacturer of color graphic computer systems, and Telecorp Systems, which 
builds voice response and telephone call processing computers. He has 
a BSEE from the University of Virginia and is currently seeking an MBA 
at Georgia State University. Robert has been programming computers 
for 23 years, with 10 years of C experience, and has been designing 
hardware for over 15 years. He can be contacted at 5011 Brougham 
Court, Stone Mountain GA 30087. 
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Listing 1 (tospkr.c) 

/* 

* Play an audio file file out the PC speaker. 

* Written for Turbo C 2.0, by Bob Bybee, 7/91 

* 

* usage: tospkr <filename> [<bits>] 

* 

* <filename> is the audio file to be played. 

★ 

* <bits> is the number of speaker bits per sample. 

* if not entered, it will be calculated. 

*/ 

#include <stdio.h> 

#include <stdlib.h> 

#include <mem.h> 
linclude <bios.h> 

#include <alloc.h> 
linclude <dos.h> 
linclude <conio.h> 

lifndef _LARGE_ 

lerror must use LARGE memory model! 
lendif 

/* audio sample rate, per second */ 

Idefine SAMPRATE 8000 

/* 

* 80x86 opcodes for the instruction sequences we 

* will need, in order to drive the PC speaker. 

* 


* 

On entry. 

to 

set up 

the registers 

★ 

BA 61 

00 

mov 

dx,61h 

* 

B5 4A 


mov 

ch,4ah 

* 

B1 48 


mov 

cl,48h 


* 


* (Note: the 4a/48 values, at offset 4/6, should be 

* changed to agree with the current value of port 61H.) 

* 

* To set the speaker bit high: 

* 8A C5 mov al,ch 

* EE out dx.al 

* 

* To set it low: 

* 8A Cl mov al,cl 

* EE out dx.al 

* 

* A "far return" to end the routine: 

* CB retf 

*/ 

unsigned char ops_begin[] = 

(Oxba, 0x61, 0x00, 0xb5, 0x4a, Oxbl, 0x48}; 
unsigned char ops_high[] = {0x8a, 0xc5, Oxee}; 
unsigned char ops_low[] ■ {0x8a, Oxcl, Oxee); 
unsigned char ops_end[] = {Oxcb}; 

/* input buffer size, and pointer to it */ 

Idefine INBUFSIZE 65000U 
unsigned char *inbuf; 

/* array of audio segment lengths in file */ 

Idefine MAX_SEGS 200 
unsigned int seg_length[MAX_SEGS]; 
unsigned int num_segs = 0; 
char gotjengths » 0; 

/* PFV is a pointer to a function taking 

* no args, and returning void */ 
typedef void (*PFV)( void ); 

PFV playfuncs[256]; 

unsigned int bits_per_sample; 


Bit one of the same port (61H) drives the speaker directly. 
When this bit is set to 1, the circuit applies a constant voltage 
to the speaker cone, forcing it in one direction. When this bit 
is 0, the speaker has no voltage applied and returns to its 
normal, resting position. By turning this bit on and off rapidly, 
software can generate a tone of any desired frequency. 

To compare the two methods, imagine a program that 
generates a 1000 Hz tone for one second. Using the program¬ 
mable timer, software would set the speaker to generate 
1000 Hz, enable it by setting port 61H bit zero, do nothing for 
one second, then clear port 61H bit zero. Alternatively, using 
port 61H bit one, software would have to set the bit, wait 
.0005 seconds, clear it, wait .0005 seconds, and repeat this 
loop 1000 times. This process is a lot more difficult, especially 
since a short delay time like .0005 seconds must be generated 
using a carefully timed set of instructions. The number of in¬ 
structions varies depending on CPU type, clock speed, memory 
speed, and so on. 

Digital vs. Analog Waveforms 

Both of these techniques can generate a square wave, 
such as the one in Figure 1. When reproducing a square wave, 
the speaker position is either “on” (full extension) or “off (rest¬ 
ing). There is no intermediate position. But to play recog¬ 
nizable voice or high-quality music, the hardware must be 
capable of doing much more. 

Figure 2 shows a portion of a voice waveform. It contains 
many points between the two extremes of the square wave. 
Some computers use a digital-to-analog converter (DAC) to 
drive the speaker. These systems can more closely ap¬ 
proximate the intermediate values that a voice waveform re¬ 
quires. A Macintosh, for example, uses an 8-bit DAC, capable of 
producing 256 different speaker positions. A compact-disc 
player uses 16 bits for 65,536 possible positions and very high 
quality. 

Figure 3 illustrates the same voice data used in Figure 2, 
but “quantizes” it into four discrete levels (as a two-bit DAC 
would). As a digital system uses fewer bits to represent the 
waveform, its output has fewer distinct levels, and becomes 
less like the original analog voltage. The PC has the equivalent 
of a one-bit DAC, with only two positions: on and off. Running 
the voice waveform through a one-bit DAC looks like Figure 4 
and sounds like pure distortion. 

A Mechanical Integrator 

The CPU is many times faster than the speaker. When the 
CPU sets port 61H bit one, the speaker tends to be driven 
outward. But because the speaker is a mechanical device and 
has inertia, it does not attain its maximum excursion immedi¬ 
ately. 

Suppose that before the speaker reaches its maximum 
position, the CPU clears port 61H bit one. The driving voltage 
disappears, and the speaker tries to return to its original posi¬ 
tion. Now, if the CPU sets and clears this bit very rapidly, the 
speaker experiences approximately half the driving voltage it 
did before (since the bit is on only half the time). The resulting 
position falls halfway between the two extreme points. 

This method, called pulse-width modulation, can be used 
to set the speaker anywhere between its “off” and "on” posi¬ 
tions. By varying the ratio of ones and zeros fed to port 61H 
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bit one, a program can set the speaker position with fairly 
good accuracy. The speaker acts as a mechanical integrator, 
and follows the average voltage fed to it, since it is too slow 
to respond to every bit the CPU writes. 

How Many Bits? 

In any digitizing application, the more bits the program 
uses, the better. To maximize this algorithm's quality, the 
code should try to force as many bits per second to the 
speaker as it possibly can. 

Suppose l recorded a file of digitized audio, using a sam¬ 
pling rate of 8000 samples per second. If I recorded this file 
with an 8-bit analog-to-digital converter (ADC), each sample 
could have 256 possible levels. To reproduce the sound, the 
CPU must fetch a new sample from the file every 1/8000 
second (125 microseconds), and feed some ones and zeros to 
the speaker so that the speaker moves to its new position. 

If the sample's value were 00, all bits sent to the speaker 
would be zeros. If the sample were FFh, all bits would be 
ones. For a sample of 80h, the bits would alternate between 
ones and zeros, positioning the speaker somewhere in the 
middle of its range. 

Ideally, the program should push 255 bits to the speaker 
for each sample. The number of ones sent in each sample 
would equal the value of the sample. Sample OOh would have 
no ones, 80h would have 128 ones (evenly distributed among 
the zeros, please). In sample FFh, all 255 bits would be ones. 
Unfortunately, I haven't found a method of pushing 255 bits 
out to the speaker, 8000 times per second. To do so, I would 
have to write a new value to port 61H, (8000 x 255) times per 
second, or one every 0.49 microseconds. 

Even if new CPUs were that fast, the program should run 
correctly on all PCs, not just the fastest ones. The program 
should adapt itself to the speed of the PC it is running on, and 
push as many bits to the speaker as that PC is capable of 
doing. 

Assembly Required 

The fastest way to send bits to the speaker is in a series of 
instructions: 

mov al.ch 
out dx.al 
mov al,cl 
out dx,al 


If ch is preloaded with a value that has bit one set, cl has 
the same value but with bit one clear, and dx contains 61H 
(the port number), this code will slam bits to the speaker as 
fast as the CPU can run. The program can read from port 61H 
to determine what other bits are currently set. The other bits 
in port 61H are used to control other devices on the PC’s sys¬ 
tem board, and should be left alone. 

The system's speed determines how many mov/out instruc¬ 
tion pairs can be executed in 125 microseconds. The program 
finds this number experimentally, then assembles the proper 
number of opcodes in dynamically allocated memory. The 


Listing 1 — Cont’d 

/* prototypes */ 
void patch_opcodes{ void ); 
int best_rate( void ); 
int test_time( int n_bits ); 
void generate_codes( void ); 


void main( int ac, char **av ) 

{ 

FILE *fp; 

unsigned int nbytes, len, seg, n_to_read; 
unsigned char *p; 

-ac; 

++av; 

if (ac < 1) 

( 

printf(“usage: tospkr <voicefile> [<bits>]\n"); 
exit(l); 

) 

/* open the input file */ 

if ((fp = fopen(*av, "rb")) == NULL) 

{ 

printf(“Can't open voice fil^: %s\n“, *av); 
exit(l); 

} 

/* allocate memory for the input buffer */ 
if ((inbuf = calloc(l, INBUFSIZE)) == NULL) 

{ 

printf ("Can't get memory for input bufferin' 1 ); 
exit(l); 

} 
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Listing 1 

— Cont’d 

/* get the current value of port 61H */ 

/* 

patch opcodes!); 

* Calculate the number of bits we can play to the 


* speaker, for each audio sample, in order to make 

if (ac >* 2 M (bits per sample - atoi(av[1])) > 0) 

* the playback come out at SAMPRATE samples 

; /* got our sample rate on the coimand line */ 

* per second. 

else 

*/ 

bits_per_sample • best_rate(); 

int best rate( void ) 

/ 

/* Create the 256 executable functions */ 

I 

int bitsl, bits2, ticksl, ticks2; 

generate_codes(); 

float fbits; 

/* See if the file is prefixed with a list of audio 

/* Start with 10 bits/sample. Double it until 

* segment lengths. If so, read it into the 

* it takes at least one second (18 ticks) */ 

* seg length[] array. It contains unsigned ints. 

printf("I'm timing your CPU, please wait...\n"); 

* zero-terminated. 

bitsl 1 10; 

*/ 

while ((ticksl * test time(bitsl)) < 18) 

fread(inbuf, 4, 1, fp); 

bitsl *- 2; 

if (memcmpfinbuf, ■LIST", 4) ** 0) 


{ 

/* Now time it at 5x this number of bits. */ 

got lengths - 1; 

bits2 = bitsl * 5; 

do { 

ticks2 * test time(bits2); 

fread(&len, 2, 1, fp); 


seg length[num segs++] * len; 

/* Interpolate to get the optimum number of bits 

} while (len != 0); 

* per sample for this PC. */ 

i 

fbits ■ (18.2 - ticksl) * (bits2 - bitsl); 

else 

fbits - fbits / (ticks2 - ticksl) + bitsl; 

; /* We could rewind here, but 

return ((int)fbits); 

* 4 bytes isn't worth it. 

*/ 

) 

/* Read in the file and play it thru the speaker. 

/* 

* On each read, get the next segment's worth (if a 

* Build a set of instructions into inbuf, which will 

* list of segments exists), or as much as we can. 

* play n bits out to the speaker. Return the number 

*/ 

* of BIOS ticks it takes to play this many bits out, 

for (seg = 0; ; ++seg) 

/ 

* SAMPRATE times. 

*/ 

int test time( int n bits ) 

n to read * 

got lengths ? seg length[seg] : INBUFSIZE; 

( 

if (n to read ** 0 || 

unsigned char *p; 

(nbytes = fread(inbuf, 1, n to read, fp)) <* 0) 

int i; 

break; 

long tl, t2; 

PFV testcode; 

p = inbuf; 


disable(); 

p * inbuf; 

memcpy(p, ops begin, sizeof(ops begin)); 

/* For each byte, call one of 256 functions which 

p +■ sizeof(ops begin); 

* were created in the playfuncs[] array. 

for (i = 0; i < n_bits; ++i) 

while (nbytes- > 0) 

I 

memcpy(p, ops high, sizeof(ops high)); 

(*playfuncs[*p++])(); 

p += sizeof(ops high); 
l 

enable(); 

/ 

memcpy(p, ops end, sizeof(ops end)); 

if (kbhit()) /* if a key was hit, */ 


( 

testcode - (PFV)inbuf; 

getch(); /* eat the key, */ 

tl ■ biostime(0, 0L); 

break; /* and quit. */ 

for (i - 0; i < SAMPRATE; ++i) 

} 

(‘testcode) (); 

} 

t2 * biostime(0, 0L) - tl; 

printf("bits: %d ticks: %d\n", n bits, (int)t2); 

fdose(fp); 

return (int)t2; 

exit(0); 

) 

) 

/* 

/* 

* Read from port 61H. Use this value with bit 1 

* Generate opcode streams, in allocated memory, to push 

* set and cleared, in ops begin[] opcodes. 

* the proper bit patterns out to the PC speaker. 

*/ 

*/ 

void patch opcodes( void ) 

fdefine DEBUG WAVE 0 /* 1 to enable printouts */ 

( 

void generate codes( void ) 

int val; 

{ 

unsigned char *p; 

val * inportb(0x61); 

unsigned int value, sum, i; 

val &= ~0x03; /* lose bits 0, 1 */ 


ops begin[6] = val; 

printfCgenerating code for %d bits per sample...\n“, 

ops begin[4] » val | 0x02; /* add bit 1 */ 

bits per sample); 

) 

for (value = 0; value < 256; ++value) 

( 

/* Get memory for the next instruction stream 
* we're going to create. */ 

p - calloc(l, sizeof(ops_begin) + sizeof(ops_end) + 
bits_per_sample * sizeof(ops_high)); 
if (p == NULL) 
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program actually assembles 256 routines in this manner, so 
that for every byte value in the file, exactly one routine is 
called. Each of these routines takes 125 microseconds to ex¬ 
ecute, and drives the speaker port with a set of ones and 
zeros that moves the speaker to the proper position. 

The TOSPKR Program 

TOSPKR, shown in Listing 1, implements the algorithm. The 
program takes two command-line arguments. The first 
parameter, the name of the audio data file to be played, is 
required. The second, optional argument is the number of bits 
to be fed to the speaker for each audio sample. If you already 
know your system’s speed, you can provide this number on 
the command line. If not, the program will calculate it and 
you can enter it next time. TOSPKR takes about five seconds 
to calculate this value. (Other versions of the program could 
store this value in a file so that it can be read back automat¬ 
ically.) 

The program's overall logic is: 

1. Open the input file. 

2. If the number of bits per sample is provided on the 
command-line, use it; otherwise calculate it. 

3. Create the 256 functions needed. Load pointers to these 
functions into an array. 

4. If the file contains a list of audio segment lengths, read 
in that list. This information is used to pace the disk I/O. 

5. Read the input file. For each byte of the file, call one of 
the 256 functions. 

Bits Per Sample 

The best_rate() routine determines how fast your system 
is, and therefore how many bits (per audio sample) it can 
send to the speaker. best_rate() begins with an estimate of 
10 bits per sample and calls test_time() with that estimate. 
test_time() generates instructions that send 10 bits to the 
speaker, then executes those instructions SAMPRATE times. If 
the initial estimate is correct, this process will take one 
second (18.2 BIOS ticks) to complete. 

Since the initial estimate is usually low, best_rate() 
doubles the estimate until test_time() takes at least one 
second to run. At that point the variable bitsl indiates num¬ 
ber of bits per sample, and ticksl tells the time it took (in 
BIOS ticks). 

Now the program tries a higher estimate, using bits2 
which is five times the current bitsl estimate. This calculation 
returns a larger number of ticks, called ticks2. Finally, the 
program finds the optimum number of bits per sample, using 
linear interpolation and the two-point equation of a line: 

(y - Yj) = (x - x : ) * (y 2 - / (x 2 - Xj) 

The x’s are the number of bits, and y's are the elapsed time in 
ticks. The target y is 18.2 ticks (one second), and x is the num¬ 
ber of bits necessary to create this y. Letting y = 18.2 and 
solving for x, 

x = (18.2 - yj) * (x 2 - Xj) / (y 2 - y^ + Xj 


Listing 1 — Cont’d 

i 

printf("out of memory at value %d\n", value); 

exit(l); 

I 


piayfuncs[value] = (PFV)p; 


#if DEBUG WAVE 


printf("\n%3d: ”, value); 


fendif 


memcpy(p, ops begin, sizeof(ops 

begin)); 

p +- sizeof(ops_begin); 


/* evenly distribute the ones ovir the bits. */ 

sum = 0; 


for (i = 0; i < bits per sample; 

( 

++i) 

sum += value; 


if (sum >« 255) 

/ 


i 

sum -= 255; 


memcpy(p, ops high, sizeof(ops high)); 

#if DEBUG WAVE 


putchar('l'); 


#endif 

i 


else 


memcpy(p, ops low, sizeof(ops low)); 

#if DEBUG WAVE 


putcharC. 1 ); 


#endif 


/ 

p +* sizeof(ops low); 
l 


memcpy(p, ops end, sizeof(ops end)); 

} 

i 

/* End of File */ 
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Generating The Audio 

The TOSPKR program illustrates how to play an audio 
file through the PC speaker with moderately good quality. 

But where did that file come from in the first place? 

To generate a file with music or sound effects, you 
need a development system capable of converting audio 
into a digital file. Several companies build PC-bus boards 
for telephone applications such as voice-mail. These can 
record (and play) telephone-quality digitized audio, which 
has about 3000 Hz bandwidth, and is perfectly adequate 
for PC-speaker applications. 

Some sources for these telephone-interface boards are: 

• Innovative Technology Inc., Roswell GA. 

• Dialogic Corporation, Parsippany, NJ. 

There are others. Most electronics and software journals 
contain ads for companies that sell voice response applica¬ 
tions systems. All of these systems use some kind of digi¬ 
tal audio board. You can also use any standard analog-to- 
digital converter board, if it can capture audio levels at 
about 8000 samples per second. 


Listing 2 (u2bin.c) 

/* 

* Convert a Mu-Law encoded file to offset binary. 

if (ac >* 3 && (expon = atof(av[2])) > 0.0) 

* Written for Turbo C 2.0, by Bob Bybee, 7/91 

; /* use command-line exponent */ 

★ 

else 

* Usage: u2bin <infile> <outfi1e> [expon] [clip] 

expon = DEFAULT_EXP; 

* infile is Mu-Law encoded file 

if (ac >= 4 && (clip - atof(av[3])) > 1.0) 

* outfile is offset binary file for TOSPKR 

; /* use coamand-1ine clipping */ 

* expon is exponent for uncompression (optional) 

else 

* clip is clipping factor (optional) 

clip = DEFAULT_CLIP; 

* Defaults of expon = 3, clip = 5 seem to sound good. 

/* Create data translation table for these 

*/ 

* values of expon and clip. 

#include <stdio.h> 
finclude <stdlib.h> 
linclude <math.h> 

*/ 

for (i = 0; i <= 127; ++i) 

{ 


mag = clip * 127.0 * pow((127 - i) / 127.0, expon); 

Idefine DEFAULT EXP 3.0 

if (mag > 127.0) 

fdefine DEFAULT CLIP 5.0 

mag = 127.0; /* clip */ 


xl at [i] = (int)mag; 

int xlat [128]; 

) 

void main( int ac, char **av ) 

/ 

/* Read in the file and translate each byte. 

V 

while ((c in = getc(in fp)) != EOF) 

int c in, c out, sign, i; 

FILE *in fp, *out fp; 

( 

float mag, expon, clip; 

if (cjn <= 127) 


sign = 1; 

/* See if <infile> and <outfile> were given, 

else 

* open them if so. 

*/ 

-ac, ++av; 

sign =■ -1; 

c out = (sign * xlat[c in & 127]) + 127; 

if (ac < 2) 

/ 

putc(c out, out fp); 

i 

i 

printf("usage: u2bin <infile> <outfile> “ 

/ 

"[expon] [clip]\n"); 

fclose(in fp); 

exit(l); 

1 

fclose(out fp); 
exit(0); 

if ((in fp = fopen(*av, "rb")) == NULL || 

/ 

(out fp = fopen(av[l], "wb")) == NULL) 

/ 

/* End of File */ 

printf("can't open fileslW); 
exit(l); 

I 



ITI's board records 8000, 8-bit samples per second, but 
encodes its files using the telephone industry's Mu-Law 
compression algorithm. Listing 2, U2BIN.C, converts these 
files into the offset binary files used by TOSPKR. U2BIN un¬ 
compresses the Mu-Law data and clips it to make it louder 
on the PC speaker. Any distortion introduced by this 
process is buried in the inherent PC speaker distortion. 

Some of Dialogic's new boards can record Mu-Law data 
files. Their older boards use only Adaptive Delta Pulse Code 
Modulation (ADPCM), which reduces the storage require¬ 
ments by recording only 6000, 4-bit samples per second. 
ADPCM files can be converted into offset binary, but the 
method is more complex and the sound quality isn’t as 
good, other audio boards may record in a format different 
from either of these. Be sure you obtain information on the 
data format used by the audio board you plan to buy. □ 
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The code plugs in bitsl for xj, ticksl for yi, and so on. 
These calculations are done in floating-point, which doesn't 
cost much time since they are only done once. (See sidebar 2.) 

Interestingly enough, the optimum number of bits does not 
always increase as the system speed increases. A fast 80286 
can push about 113 bits per sample-, some 80386 machines 
can do only 65. This fact tells me that not all of the instruc¬ 
tions gained speed as Intel built faster processors. The par¬ 
ticular set of instructions in this code actually runs slower on 
a 386. 

Generating Instruction Streams 

Now that the program knows how many bits per sample it 
should play, it calls generate_codes() to create 256 ex¬ 
ecutable functions in dynamically allocated memory. This may 
be the ultimate in self-modifying code, since it generates far 
more code dynamically than the program originally contained! 

Each of the generated functions begins with the opcodes in 
the ops_begin[] array, and ends with the opcodes in 
ops_end[]. In between, there are bits_per_sample copies of 
either the ops_high[] or ops_low[] array. ops_high[] con¬ 
tains opcodes which push a 1 out to the speaker, and 
ops_low[] writes 0 to the speaker bit 

The distribution of ones and zeros is controlled by a 
“division by overflow" method. It uses a variable called sum, 
which begins at zero and is repeatedly augmented by the 
current value (0 to 255). Each time sum 
reaches 255, it's time to write a J to 
the speaker-, otherwise the speaker gets 
a 0. This has the effect of evenly dis¬ 
tributing the ones and zeros, for a 
smooth output waveform. Try running 
this code with DEBUGJ/AVE set to 1 to 
see how the ones and zeros are dis¬ 
tributed. 

Segment Lengths 

If the audio file is more than a few 
seconds long, TOSPKR must pause oc¬ 
casionally to read in more data from 
disk. These annoying pauses are less 
obvious if you can make them occur 
during natural breaks in the audio (be¬ 
tween sentences, if you're playing 
speech). 

TOSPKR looks for a special prefix in 
the audio file: the character string 
"LIST". If it exists, the program as¬ 
sumes it is followed by a list of audio 
segment lengths, each of which is an 
unsigned integer less than the input 
buffer size. TOSPKR reads these lengths 
into the seg_length[] array, and uses 
them as the number of bytes to read 
(n_to_read) during each disk read 
operation. 


The Results 

TOSPKR runs on even the slowest PC and XT systems. The 
number of bits per sample on these systems is very low, 
however, so the playback quality is not exceptional. A 
reasonably fast 286 or 386 produces acceptable quality for 
voice or sound effects. 

The speaker's location and the amplifier circuit used to 
drive the speaker also have a great effect on the sound 
quality. In some PCs the speaker is buried so deep in the 
chassis that nothing will sound good unless you remove the 
system's cover. 

If you order this issue’s source code disk, you'll not only 
get the source to all of this article's programs, but the ex¬ 
ecutable for TOSPKR and some sample audio files as well. 
These files give you an idea of how your programs could 
sound if you added audio playback using these techniques. 

Thanks To... 

I am indebted to Art Blake, software engineer at Innovative 
Technology Inc., for his enthusiasm and assistance in refining 
the algorithms presented here. □ 
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A Borland Compiler Floating-Point ‘Feature’ 


While testing the TOSPKR program, Windows™/DOS 
Developer's Journal editor Ron Burk discovered the pro¬ 
gram wouldn’t run on one of his 80286-based systems. He 
narrowed the problem down to the floating-point expres¬ 
sion that calculates fbits. The code simply wasn't storing 
a value into the result 

The problem turned out not to be in the program or in 
Ron's hardware. Because of the way Borland's C compilers 
do floating-point, this bug will show up in a small number 
of systems. If you distribute programs compiled with 
Turbo C or Borland C++, you should be aware of this prob¬ 
lem and a work-around for it 

These compilers allow you to select one of three float¬ 
ing-point options: 

none - Use this if your program contains no floating¬ 
point at all. 

80x87 - Use this if you're positive that your program 
will always run on a system with a numeric coprocessor. 

emulation - When the program starts, it determines if 
there's a math coprocessor in the system. If so, it uses the 
chip. If not, it uses the floating-point emulation library. 

The problem is caused by the method Borland uses to 
detea an 80x87 chip. During startup, the program makes a 
call to BIOS interrupt 0x11, the “equipment list" BIOS ser¬ 


vice. Upon returning from this call, AX contains bits that 
tell what equipment is installed. Bit one is supposed to be 
set if there is an 80x87 in the system, and cleared if not. 
Some clone systems don’t set this bit properly. See Listing 
3. 

If your system has this problem, you can override the 
auto-deteaion code using an environment variable. Insert 
the statement 

87=N 

in your AUTOEXEC.BAT, or type it at the DOS prompt. If you 
compile your program with the emulation setting, this en¬ 
vironment variable forces it to use the floating-point 
emulation library and not even look for an 80x87. 

This behavior and the 87 environment variable are 
documented in Chapter 7 of the Borland C++ Programmer’s 
Guide, and Chapter 12 of the Turbo C User's Guide. 
Borland's other product. Turbo C++, probably does floating¬ 
point the same way, but I have not had an opportunity to 
use that compiler. 

This bug appears only when running on 80286 and 
higher CPU types. On 8086/8088 processors, Borland always 
tests for an 8087 directly, without using the BIOS call. □ 
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sidebar.c 


/* 

* Print BIOS equipment list from "int 0x11". 

* Written for Turbo C 2.0, by Bob Bybee, 9/91. 

* 

* Bit 1 is set if the BIOS thinks there's an 80x87 

* installed, clear if not. See any BIOS book for 

* detailed descriptions of the other bits. Not all 

* BIOS versions use these bits in the same ways. 

*/ 

linclude <stdio.h> 
linclude <dos.h> 

void main( void ) 

{ 

union REGS regs; 

unsigned int ef; /* equipment flags */ 

int86(0xll, &regs, &regs); /* ask BIOS for it */ 
ef ■ regs.x.ax; /* copy the AX value */ 

printf(“Selected BIOS equipment flags from INT 0xll:\n"); 
printf(" math coprocessor: %u\n", (ef » 1) & 1); 
printf(” initial video mode: %u\n", (ef » 4) & 3); 
printf("# of diskette_drives: %u\n", ((ef » 6) S3) + 1); 
printf(” # of com ports: %u\n", (ef » 9) S 7); 

printf(" # of lpt ports: %u\n”, (ef » 14) S 3); 

) 

/* End of File */ 
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Turbo Pascal For Windows’ 
PCHAR Type 



Richard R. Sands 


Introduction 

In the beginning, Pascal ran on word-oriented rather than 
byte-oriented machines. In order to accommodate both time and 
space efficiency, Pascal supported two types of strings: ARRAY OF 
CHAR (big, but efficient character accessing) and PACKED ARRAY 
OF CHAR (characters packed into words, to save space). Then 
came Turbo Pascal and the STRING type. The PACKED ARRAY OF 
CHAR was tossed out the door foreverl STRINGS allowed you to 
assign, index and concatenate without having to call special 
functions. They were easy to use and everyone loved them. 

With the release of Turbo Pascal for Windows, Borland intro¬ 
duced a new type: PCHAR. PCHARs are a lot like the old PACKED 
ARRA YS in that you need to call special functions to do the same 
things as with the familiar STRING type. So now you have two 
types that support character strings, which causes a lot of con¬ 
fusion among Pascal programmers. This article removes that con¬ 
fusion with an in-depth look at this new data type. 


Richard Sands is the senior programmer for Management 
Compensation Group NW Inc, an Executive Benefits company. He 
has been programming microcomputers since 1978, primarily 
with Pascal and C Besides programming, brewing beer is one of 
his favorite activities. 
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What Are PCHARsl 

Although the name PCHAR implies that a PCHAR type is a 
pointer to a CHAR, it is a lot more than just that. The type 
PCHAR is actually two conceptual types that are compatible 
with each other. The first subtype is a zero-based character 
array: 

TYPE 

ZeroBasedArray = Array[0..65535] of Char; 

The second subtype is a pointer to the above type: 

TYPE 

PCHAR = ''ZeroBasedArray; 

In practice, you would usually not define a zero-based charac¬ 
ter array with such a large upper bound; you would set the 
upper bound to the size you need, something within the 
range zero to 65535. These are all examples of valid zero- 
based arrays: 

VAR 

Bufl = Array[0..9] of char; 

Buf2 = Array[0. .254] of char; 

Buf3 = Array[0..4096] of char; 



The first two variable declarations are similar to declarations 
of STRING[10] and STRING, respectively. The third declaration 
has no STRING equivalent, since Turbo Pascal limits STRING 
lengths to 255 characters. 

Although type PCHAR is conceptually defined as a pointer 
to a zero-based character array, it supports a quite different 
syntax for dereferencing. Rather than using the normal 
dereference operator O, you use the standard array index 
operators ([]). This is the root of much of the confusion about 
PCHARs; this looks like array syntax, but you get into trouble if 
you forget that a PCHAR is really a pointer and not an array. I 
will cover this point in more detail in a later section. 

PCHARs Vs. STRINGS - Pros And Cons 

Both PCHARs and STRINGS perform the same function: they 
allow you to manipulate strings of characters as a single unit 
instead of as a series of characters. Since Windows is oriented 
towards C more than Pascal, the Windows API uses PCHARs 
(also known as “null-terminated strings”) extensively. Both 
STRINGS and PCHARs have advantages and disadvantages and 
a Windows program can use both. Knowing when to use one 
instead of the other is important. 

In general, PCHARs are more efficient and more flexible 
than STRINGS. STRINGS are much easier to work with in Pascal, 
however. Unfortunately, in Windows programming, you will 
tend to use PCHARs more than regular STRINGS. I have found 
STRINGS best for situations that call for parsing strings into 
fields or substrings, because of the simplicity of using 
Delete(), Copy(), and the + operator. 

Here are the basic differences between STRINGS and 
PCHARs-. 

The Compiler Automatically Allocates STRINGS. Turbo Pascal 
for Windows allocates temporary strings as needed when 
evaluating string expressions. This is a double-edged blade. On 
the one hand, it relieves you from handling all the details of 
variable-length strings (including creating temporary strings to 
evaluate a string expression). On the other hand, the compiler 
generates code that allocates, copies, and deallocates lots of 
strings. That means you are trading both time and memory 
for the simplified syntax. Doing the work by hand, using 
PCHARs, can result in much faster and smaller code. 

In the following example, the compiler allocates two tem¬ 
porary 255-character strings. 

S := Uppercase(S) + 'Test' 

First, the generated code allocates a 255-byte temporary 
string and copies the result of the Uppercase () function to it. 
Next, the code allocates another 255-byte temporary string 
and copies the first temporary string, followed by the literal 
‘Test' into it. Finally, the code copies this second temporary 
string into the variable S and deallocates both temporary 
strings. 
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Using PCHARs, you could recode the previous example like 
this: 

StrCat(Uppercase(S), 'Test')); 

This does not have the overhead of the temporary strings 
since you are providing the neccessary memory for S. 

STRINGS Are Limited To 255 Characters. This is because the 
Oth byte of a STRING contains the length of the string. Since 
that length byte only holds an eight-bit number, the valid 
range for a string is zero to 255 characters. PCHARs do not 
contain a length byte, so they may be as long as one seg¬ 
ment (65536 bytes). However, since PCHARs have no length 
byte, they need some other means to mark the end of the 
string. Instead of a length byte, PCHARs use a NULL (zero) byte 
to delimit the end of the string. 

You can understand the difference between these two 
storage schemes by looking at the two corresponding string 
length functions. Length() returns the length of a STRING by 
merely returning the value of its Oth byte (the compiler can 
generate this code inline). StrLen(), on the other hand, 
returns the length of a PCHAR by scanning until it locates a 
NULL byte. Listing 1 illustrates the algorithm with a Pascal ver¬ 
sion of StrLen(). 

Because PCHARs can be 64kb long, they lead to great ef¬ 
ficiencies when writing PCHAR strings to a window, since you 
can refer to complete pages of text with a single PCHAR vari¬ 
able. 

STRINGS Can Be Assigned Directly. You can use the assign¬ 
ment operator (:=) to copy one STRING variable to another, a 
very convenient syntax for a common task. When you use 
PCHARs, you must call a function to do this. If 5 is a STRING, 
this is a valid assignment 

S := 'This is a test'; 

If, however, 5 is a PCHAR, you must call a function to copy 
another string to it 

StrCopy(S, 'This is a test'); 

You can use the assignment operator on PCHAR variables, but 
it assigns the "pointer” value of one PCHAR to another. This is a 
valid use if you are sure that you intend to have two pointers 
to the same array of characters, and that the PCHAR receiving 
the new value does not have any memory already associated 
with it since it would be lost Here is an example (assuming SI 
and S2 are of type PCHAR, and SI has been initialized to point 
to a zero-based array of characters): 

StrCopy(Sl, 'Test'); 

S2 := SI; 

Writeln(S2); 

StrDispose(Sl); 


Listing 1 

Function StrLen(S:PCHAR):Word; 

var I:Word; 

begin 

I := 0; 

while (i<$FFFF) AND (S[i] <> 0) do 
inc(i); 

StrLen := i 

end; 

{ End of File } 


In this example, S2 is made to point to the same array of 
characters as SI. Notice that StrDispose() is called for SI, but 
not S2. Since they both refer to the same array, it would be 
an error to call StrDispose() for both pointers. 

STRINGS Can Contain A NULL Character. Since PCHARs 
reserve NULLs (#0) to mark the end of strings, you cannot use 
the value zero in an actual string. This can cause problems if 
you are dealing with binary data. Consider the following code 
fragment, in which S is a STRING variable: 

S:= 'NULLs '#0' are OK' 

Writeln(S); 


Programming Secrets Now on Video! 
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I CPI (206) 779-9508 

* Substantial discounts are available to TU(b members; call for details, y 

□ Request 251 on Reader Service Card □ 

Windows/DOS Developer’s Journal - Page 49 


December 1991 











Has Your 
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Expired? 

The numbers on your 
mailing label appear as: 

10000 #07.1 08.3 
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Windows/DOS Developer’s 
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In this case, Uriteln() dutifully writes 
the string, including the NULL byte in 
the middle. But what if you do this with 
PCHARs! You might try something like 
this: 

StrCopy(S, 'NULLs '#0' are OK'); 
Writeln(S); 

In this case, Uriteln writes out the 
string NULLs and stops. The reason is 
that StrCopy() stopped copying when 
it hit the NULL byte. 

Just remember that NULL bytes and 
PCHARs do not mix. If you need to use 
zero character values, either use 
STRINGS, or treat them as regular BYTE 
or CHAR arrays and use the Move() pro¬ 
cedure. 

STRING s Support The u +” Operator. 

The concatenation operator for STRINGS 
is the + symbol. This makes it easy to 
write an expression that concatenates 
several strings together into a single 
string. Again, this is quite convenient, 
since you can have an expression like 
this: 

S := 'This is a '; 

S := S + 'Test'; 

With PCHARs, you need to call two func¬ 
tions, StrCopy() and StrCat() to per¬ 
form the same operation: 

StrCopy(S, 'This is a '); 

StrCat(S, 'Test'); 


You Can Compare STRINGS With 
Relational Operators. You can use rela¬ 
tional operators (<, <=, >, >=, <>, and so 
on) to compare STRINGS. Personally, I 
think this makes your code quite 
readable whereas with PCHARs you 
must call StrCompO to compare two 
strings. StrCompO returns -1, 0, and 1 
to indicate that its first string argument 
is, respectively, less than, equal to, or 
greater than its second string argument 
However, using StrCompO is much 
more flexible since it returns one value 
that represents the result of the com¬ 
parison. Plus, with STRINGS, you cannot 
have variable operators; in other words, 
you cannot have a variable that repre¬ 
sents which operator you want to use, 
like this: 

Function Test(Sl, S2:PCHAR;\ 

Op:Integer):Boolean; 

begin 

Test := StrComp(Sl, S2) = Op 
end; 

With STRINGS, you would need to write 
a function as: 

Function Test(Sl, S2:String; 

Op:Integer):Boolean; 

begi n 

case Op of 
-1: Test := SI < S2; 

0: Test := SI = S2; 

1: Test := SI > S2; 
end; 
end; 


Listing 2 


Function StrAssign(VAR Dest:PCHAR; Source:PCHAR):PCHAR; 

{ Allocate memory and copy existing source to dest. This first 
deallocates dest's memory if required. } 
begi n 

if Dest <> NIL then StrDispose(Dest);{ Deallocate Dest } 
if (Source = NIL) OR (Source[0] = #0) then 

Dest := NIL { No source string so return NIL ) 

el se 
begin 

GetMem(Dest, StrLen(Source)+l ); { +1 for the 0 byte } 
StrCopy(Dest, Source) 
end 


{ End of File } 
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Although, once you want to add <= or 
>= operators, your PCHAR routine ends 
up with a case statement too. 

String Indexing Is Less Flexible. In 
general, both STRINGS and PCHARs are 
equally adept at character indexing. The 
one thing you can do with a PCHAR that 
you can't do with a STRING is reference 
a PCHAR in the middle of its data. In 
other words, to use the right-most por¬ 
tion of a STRING, you have to call a 
function: 

S := ‘1234567'; 

Writeln( copy(S, 4, 4)); 

{ writes '4567' } 

With PCHARs, all you have to do is use 
the address-of operator {&): 

StrCopy(S, '1234567'); 
Writeln(@S[3]); 

This is not a big advantage, but you'd 
be suprised how often this form is used. 

STRINGS Can Be Passed By Value. 
You can declare procedures that accept 
STRING parameters either by value, or 


by reference (VAR parameters). Using a 
VAR parameter allows your procedure 
to change the caller's string, but you 
can also pass the value of the string (a 
copy of it) by omitting the VAR 
keyword. This allows your routine to 
change the value of the copy without 
changing the original string. 

PCHAR really does not support pass¬ 
ing strings by value. Since a PCHAR is a 
pointer, you can pass that pointer by 
value, but it still refers to the same 
string. This is another case where you 
have to write explicit code if you want 
to emulate a STRING. To pass a PCHAR 
string by value, you would first allocate 
a temporary array, copy the string into 
the temporary, call the function, then 
deallocate the temporary array. 

You can pass a PCHAR as a VAR 
parameter, but you should do this only 
when you want to be able to change 
the caller’s pointer. Listing 2 shows an 
example of passing a PCHAR as a VAR 
parameter. The advantage of Str- 
Assignf) is that it will first deallocate 
any memory associated with the des¬ 
tination pointer before allocating a new 


array. This does assume the caller set 
the destination pointer to NIL initially. 

PCHARs Allow Pointer Arithmetic. 
You can add or substract an offset to a 
PCHAR variable to make it point to dif¬ 
ferent characters in the array. Rewriting 
the previous StrLenf) example to use 
pointer arithmetic produces: 

Function StrLen(S:PCHAR):Word; 
var P : PCHAR; 
begin 
P := S; 

while P[0] <> #0 do 
inc(P); 

StrLen := P - S 
end; 

To obtain the length of the string, this 
function subtracts the pointer to the 
beginning of the string from the pointer 
to the end of the string. Note that you 
should only subtract two PCHARs if they 
both point into the same string. 

PCHARs As Literals 

STRING literals and PCHAR literals look 
the same - they are both quoted strings 
of characters. However, the compiler 
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looks at the way that you use them to 
determine if they are indeed PCHARs or 
STRINGS. For example: 

{a STRING literal} 

writeln( 1 This is a test 1 ); 

(a PCHAR literal} 

P := StrNew(‘This is a test 1 ); 

Since the compiler knows that Str- 
New() takes a PCHAR argument, it as¬ 
sumes that literal argument is a zero- 
based array of characters. As with the 
STRINGS, you can include literal charac¬ 
ters in a PCHAR literal: 

P := StrNew('This is’^M#10'a 
test'); 

Note that the compiler does not auto¬ 
matically convert a STRING to type 
PCHAR. If you have a STRING variable, 
and pass it to a routine that expects a 
PCHAR, you will get a type mismatch. Do 
not try to type-cast it, as that will not 
produce the expected result This will 
produce an error, if 5 is a STRING: 

Procedure Test(XrPCHAR); 
begin 

end; 

{...} 

S := ‘This is a test'; 

Test(S); { Makes a Type-Mismatch 
Compiler Error } 

Allocating PCHAR Space 

A variable of type PCHAR points to an 
array of characters. Unlike STRINGS, 


PCHARs require you to allocate an array 
large enough for your purposes. You 
can allocate space for a PCHAR either by 
declaring a zero-based array of charac¬ 
ters, or by calling GetMem() to dynami¬ 
cally obtain such an array. You can also 
call StrNew() to obtain a dynamically 
allocated copy of an existing string. 

If you dynamically obtain the array 
for a PCHAR, you are also responsible for 
deallocating that space when you are 
through using it Remember that when 
you use the PCHAR notation, you are 
dealing with pointers. This means that 
you must not reassign a PCHAR without 
first disposing of the memory it points 
to (unless you have another pointer to 
the same memory). For example, here 
is an error that the compiler will not 
catch: 

VAR S:PCHAR; 
begin 

S := StrNew('This is a test 1 ); 

writeln(S); 

S := StrNewCDifferent String'); 
end; 

This example eats up memory. Just 
remember that PCHARs are pointers, so 
they are susceptible to the same 
problems as any other Pascal pointer 
type. Watch out for dangling pointers, 
uninitialized pointers, and forgetting to 
dispose of everything you allocate. 

PCHARs as Constants 

Both STRING and PCHAR constants 
look and behave the same. Since con¬ 
stants are just symbolic ways of writing 
the constant value, a constant defined 
as: 


Listing 3 

Function StrCon(Dest:PCHAR;Letter:Char;Width, Size:Integer):PCHAR; 
begin 

StrCon := Dest; { Return Dest } 

if Dest = NIL then EXIT; { Don't fill a NIL! } 
if Width >= Size then 

Width := Size; { Always keep in bounds - don't overwrite } 

ASM 


LES 

DI, Dest 

{ Get Address of DEST in ES:DI } 

CLD 


{ Set direction forward } 

MOV 

CX, Width 

{ count in CX } 

MOV 

AL, Letter 


REP 

ST0SB 

{ make string of characters } 

MOV 

AL, 0 

{ Null Terminate } 

ST0SB 


{ and store } 


end 

end; 


{ End of File } 
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CONST Test = 'This is a test'; 

would work both in STRING expressions and PCHAR expres¬ 
sions: 

S := S + Test; 

StrCopy(P, Test); 

However, typed constants are initialized variables, so the com¬ 
piler will perform type checking: 

CONST Test : PCHAR = 'This is a test'; 

VAR S:String; 

{...} 

S := S+Test; { Err: Type Mismatch } 

Functions Of Type PCHAR 

When you write or use a function of type STRING, the 
compiler automatically allocates the space for the new string 
which is the function result. PCHAR functions, however, do not 
usually return a new string. You have to provide it with a 
variable to hold the new string. Many PCHAR functions take a 
destination and source PCHAR, and then return the destination 
PCHAR as the result: 

Function Uppercase(Dest, 

Source:PCHAR):PCHAR; 

begin 

For I:=0 to StrLen(Source)-l do 
Dest[i] := upcase(Source[i]); 

Uppercase := Dest 
end; 

In this example, the caller was responsible for allocating space 
for the destination string. Also, note that the return result is 
the address of the destination string. Since Uppercase () 
returns the Dest parameter, this allows the caller to nest 
PCHAR functions: 

StrCat( 

Uppercase(Dest,'This is a '), 

'Test'); 

To do this with STRINGS, you would write: 

Dest := Uppercase('This is a ')+ 'Test'; 

Both methods seem about the same, but when you get into 
more nestings, you must be very careful about what is being 
modified. Also, since the PCHARs are nested, you have to read 
the expression from the middle rather than left to right as 
with STRING expressions. 

PCHAR Traps 

There are several traps you must look out for when using 
the PCHARs. None of these traps are caught by the compiler, 
even if you have directives like range checking (“{$R+}") on. 
Many of these traps occur because of the tendency to use 
PCHARs like STRINGS. Some of these traps result from Borland's 


decision to avoid NIL pointer checks in their PCHAR library 
functions. 

UAEs From NIL Pointers. StrNew() allocates a copy of the 
string passed. If you pass StrNew() a NIL pointer, or a pointer 
to a string of length zero (“”), StrNew() will return NIL. The 
fact that StrNew() returns NIL when you pass it an empty 
string causes problems when you write a statement like this: 

S := StrNew(Sl); { S1[0] = #0 } 
if StrComp(S, SI) = 0 then 
{do something); 

This example generates a UAE, since the StrCompO function 
does not first check for NIL arguments. 

The trap is that your program may run for quite some time 
without any UAEs, and then, all of a sudden, start crashing 
with the dreaded UAE. This can be a hard error to track. Most 
routines in the STRINGS Unit have such unfriendly behavior. 
This was a decision by Borland to sacrifice error checking for 
efficiency. Make sure your routines test for NIL. 

Of course, a safe way to proceed is to write “wrapper" 
routines that check their parameters before calling the cor¬ 
responding library routines. Another solution would be to con¬ 
vert the PCHARs to STRINGS: 

if StrPas(Sl) = StrPas(S2) then 
{ do something }; 

but this only works for PCHAR strings less than 255 characters 
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long. It is also less efficient in speed and memory than a 
wrapper routine since the compiler needs to call two func¬ 
tions that allocate a temporary string on the stack. 

Assignment Trap. You can assign one PCHAR to another 
with the ;= operator. However, what you are assigning is the 
pointer value - not a copy of the string. So, although this code 
fragment apparently works, it will (eventually) generate a UAE: 

StrNew(Sl, 'This is a test'); 

S2 := SI; 

StrDispose(Sl); 

StrDispose(S2); 

Dangling References and Orphaned References. Dangling 
references are related to the previous problem. They are 
PCHARs that point to another PCHAR that you deallocated. This 
often happens because a function returns a PCHAR that is a 
local variable: 


The complement to this is orphaned memory. This can 
happen when you placed a NULL in the middle of a PCHAR 
(generally to truncate the string): 

StrCopy(P, 'Hello, World'); 

P[5] := #0; { Hello ) 

StrDispose(P); 

This is also a tricky error to catch. A safe rule is to avoid 
truncating strings - make a copy instead. 

A related error is caused by a PCHAR expression that allo¬ 
cates memory but does not result in any assigment of that 
memory: 

if StrComp(StrUpper( 

StrNew(Temp, S)), 'CON.PRN' 

) = 0 then 
{ do something }; 


Function DangTest: PCHAR; 
var S: Array[0..20] of char; 
begin 

StrCopy(S, 'Rick Sands'); 

DangTest := S 
end; 

What is so bad about this problem is that it may work for a 
while. 
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Since you are not assigning the value of Temp to anything, the 
memory is allocated and lost Always assign PCHARs to a vari¬ 
able. 

Memory Loss From Length Changes. If you want to use 
StrNew() and StrDispose (), then do not delete, insert, or 
otherwise change the length of a PCHAR string. If you delete 
characters from a string, that does not change the amount of 
allocated memory, but StrDispose() will only deallocate the 
current length (up to the first NULL byte) of the string. 

Of course insertion into a PCHAR is unsafe unless you allo¬ 
cated enough extra bytes to allow for string growth. 

Changing The Value Of Literals. This is a bizarre error that 
happens in C, but is quite unheard of in Pascal. A function can 
change the value of a string literal! For example: 

Procedure Add(S:PCHAR); 
begin 

StrCat(S, 'X'); 
end; 

{...} 

for I:=l to 5 do 
Add('X'); 

After the loop executes, either you will get a UAE or the ac¬ 
tual value of ‘X’ is now ‘XXXXXXT What is happening is that 
the code passes the address of the literal string to Add(), and 
the routine cannot tell if the parameter is a literal or a vari¬ 
able. The only protection against something like this is to use 
the VAR keyword in the procedure: 

Procedure Add(VAR S:PCHAR); 

This works, but does give a different impression. It implies 
that Add() may change the pointer value of 5. 

Prefixing PCHARs Instead of Recopying. This is related to 
the previous problem. With STRINGS, adding a prefix to a string 
is easy: 

S := 'Y' + S; 

With PCHARs, you might be tempted to do the following: 
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StrCopy(S, StrCat('X\ S)) 

This will compile and run and may even work for a while, but 
it is actually changing the value of the literal 'X' so eventually 
a UAE will be encountered. 

No Range Checking. Even when you have range checking 
("{$R+}”) enabled, the compiler cannot range check PCHAR 
variables, since a PCHAR can point to any length of string. This 
means that many, but not all, routines require that you pass a 
size parameter to prevent overwriting: 

Function GetWindowsDirectory 
(Buffer:PCHAR; Size:Word) 

: Word; 

If you do assignments or concatenation, make sure that you 
require a size parameter to protect against overwriting code 
or data. 

Using Local Zero-Based Character Arrays. Related to the 
above problems is the problem of zero-based character arrays 
as local variables in your own functions. Since these arrays 
can be quite large, you cannot ensure that the compiler can 
allocate enough memory without a stack overflow. For ex¬ 
ample: 

Procedure Test(Source:PCHAR); 
var S:Array[0..65535] of char; 
begi n 

StrCopy(S, Source); 

(...) 

end; 

would cause a stack overflow message. The solution here is to 
use PCHARs as local variables and allocate and deallocate the 
memory explicitly: 

Procedure Test(Source:PCHAR); 

var S:PCHAR; 

begin 

StrNew(S, Source); 

{ do something) 

StrDispose(S) 

end; 

Relying on the Compiler For Bounds Checking. When 
using the STRING type, you can assign a larger string to a 
shorter string because the compiler knows how many charac¬ 
ters each STRING variable can hold (so it will truncate, if 
necessary). However, if you try to assign a long character 
array to a short character array, the compiler will do it, but it 
may write past the bounds of the array, with disastrous 
results. 

Double Memory Allocation. The StrNew() function does 
not check to see if there is already memory allocated to a 
PCHAR. This can lead to loss of memory. Watch out for the 
following: 


S := StrNew('Test'); 

(...) 

S := StrNew('Another Test 1 ); 

You can write a wrapper function for StrNew() that performs 
the necessary checks, so long as you initialize your PCHARs to 
NIL. 

Forgetting Memory Allocation. This happens a lot You 
forget to allocate memory for a PCHAR and then run into the 
UAE Remember, you are responsible for allocating the space 
that a PCHAR points to. 

Destination = Source Traps. This occurs when you pass 
the same variable to a routine that requires a destination and 
a source PCHAR. The called routine may assume that the 
source and destination are distinct, and produce unexpected 
results: 


Procedure StrCatUpr(Dest, Source:PCHAR):PCHAR; 
begi n 

StrCatUpr := StrCat(Dest, StrUpr(Source)) 
end; 

(...) 

StrCopy(S, 'Test'); 

StrCatUpr(S, S); { Dest = Source } 

This does not produce TestTEST, it produces TESTTEST. When 
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you write a function like this, always assume that source and 
destination strings may be the same: 

Procedure StrCatUpr(Dest, 

Source:PCHAR):PCHAR; 
var Temp: PCHAR; 
begin 

Temp := StrNew(Source); { Make a copy ) 

StrCatUpr := StrCat(Dest, StrUpr(Temp)); 
StrDispose(Temp); 
end; 

To be on the safe side, or if you are using another 
programmer's routine, make a temporary copy of the string, 
rather than counting on the routine to assume that the source 
and destination may not be distinct 

StrPasO Limitations. Since the maximum length of a 
STRING is 255 characters, StrPasO will truncate the result if 
you try to use it on a long PCHAR. 

The Borland STRINGS Unit 

The only STRINGS Unit routines that are safe (that is, that 
check for NIL pointers) are StrNewf) and StrDispose() 
routines. StrNew() and StrDispose() are the only routines 
not written in assembly language. 

The Strlxxx() routines don't call any other routines - the 
uppercase functions are inline. In fart none of the routines 
calls any other support routines except StrNewf) and Str- 
Dispose(), which call the standard routines GetMem() and 
FreeMem(). 
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software serial data analysis package. If you work with serial 
communications, there is no wiser investment than Serialtest. 

Order Serialtest today, or request a free demo disk. 

Also, ask us about SerialBERT®, our new package that turns 
your PC into a Bit/Block Error Rate Tester. 

Frontline ™ 

Frontline Test Equipment Tel (800) 562-8378 

814 Commerce Drive (708)574-3689 

Oak Brook, IL 60521 FAX (708) 574-3703 


Both Str() and Val() are polymorphic Specifically, they 
will perform operations on either STRING s, PCHARs, or zero- 
based character arrays. 

Writing Your Own PCHAR Routines 

There are two schools of thought on writing your own 
PCHAR routines: you can write them as Borland would, that is, 
assume PCHARs are never NIL, or write them with NIL- pointer 
checks included. Writing them as Borland does leads to effi¬ 
cient and faster code, although prone to UAEs if you are not 
careful. Writing them with the NIL checks is safer, but may 
lead to unnecessary checking. Although, since you should 
check for NIL pointer at the calling routine point to be on the 
safe side, it is almost a toss-up on whether to just go ahead 
and include the checks. 

On the whole, you should write your routines assuming 
that the calling program is responsible for allocation of 
memory. This is most flexible since the caller can pass a zero- 
based character array or a PCHAR. Be careful about writing 
routines that reallocate their PCHAR parameters; you cannot 
pass a stack-based variable to such a routine. 

By convention, when assigning one PCHAR (or any other 
type) to a PCHAR, the destination PCHAR comes first in the 
parameter list of the function declaration and is returned by 
the function. This is so you can then nest these functions with 
other functions, always passing the primary variable to the 
next routine. 

If you include a parameter specifying the PCHAR length, it is 
conventionally called Size and placed last in the parameter list 

Function GetWindowsPath(Dest:PCHAR; 

Size:Word):Integer; 

The easiest way to write assembler string routines is to 
use the built-in assembler. Remember that a PCHAR is a 
pointer, so you usually want to pick that up right away: 

{ Get Address of DEST in ES:DI } 

LES DI, Dest 

The return result, if any, is always returned in the DX:AX 
register pair. 

Listing 3 shows an example of a PCHAR function that uses 
the built-in assembler and checks its parameters. This function 
accepts a character and initializes the given string with that 
letter. 

Conclusion 

In reality, although you have both the PCHAR and STRING 
types, you will find that since Windows API requires the PCHAR 
type, you will tend to use them more often than not Per¬ 
sonally, I find using the two types together in the same pro¬ 
gram more confusing than just using PCHAR type alone. 

PCHARs are initially confusing, but they can be very flexible. 
With a little care, you can use them to write clear, efficient 
Windows programs. □ 
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Using Built-In Set Types 


One of the fundamental abstract types used in computer science, a set is a col¬ 
lection of elements (or members) where the elements have a common type, often 
called the “base type.” The range of values for the set's elements is called the set’s 
“universe." 

A given element can occur at most once in a set - it’s either in the set or it isn’t. 
Unlike elements in an array, the members of a set have no inherent ordering. 

Among today’s popular programming languages, only Pascal and Modula-2 pro¬ 
vide built-in support for set types and operators. Both languages restrict the base 
type of sets in order to permit a particular implementation for sets that’s both highly 
compact and efficient. Although this built-in set mechanism isn’t appropriate for all 
applications, it's a good teaching tool and has some practical uses. 

This article describes sets as a built-in type and includes some practical examples 
using sets. Pascal and Modula-2 have different syntaxes for sets, but the underlying 
semantics are essentially the same. Since we’re more familiar with Pascal, we’ve 
used it for the discussion and examples. 

Constructing Sets 

In Pascal, square brackets do double duty as the subscript operator and as the 
set constructor. You create a value for a set simply by listing the values of the 
elements, separated by commas and enclosed in square brackets. For example, 

[2, 4, 5, 6, 7, 8] 

is a set of integers containing 2 and the values from 4 through 8, inclusive. 

For a contiguous range of values like 4 through 8, you need only specify the 
lower and upper bound, separated by a pair of dots. Thus, 

[2, 4..8] 

has the same value as the previous set. If the low bound is greater than the high 
bound, the range is taken to be empty. Thus, 

[2, 8..4] 

contains only 2. 


Dan and Nancy Saks Dan Saks is the owner of Saks & Associates, which offers consulting and training in 

C++, C, and Pascal, and is secretary of the ANSI C++ standards committee and a 
member of the ANSI C committee. Nancy Saks is Associate Professor and chair of the 
Mathematics and Computer Science Department at Wittenberg University. They have 
two sons, Ben (8) and Jeremy (5), who contributed many interruptions. Dan and Nancy 
invite readers to send comments and suggestions to them at 287 W. M cCreight Ave., 
Springfield, OH 45504, or email at dsaks@wittenberg.edu. 

















Listing 1 

const 

HT = chr(9); 

CR = chr(13); 

SPACES = HT, CR]; 

function atoi(s : string) : integer; 
var 

i, n : integer; 
neg : boolean; 

begin 
i := 1; 

while (i <= length(s)) and (s[i] in SPACES) do 
inc(i); 
neg := FALSE; 
if i <= length(s) then 
if s[i] » ' + ' then 
inc(i) 

else if s[i] = then 
begin 

neg := TRUE; 
inc(i); 
end; 

n := 0; 

while (i <= length(s)) and (s[i] in ['0' .. '9']) do 
begin 

n := 10 * n + ord(s[i]) - ord('O'); 

inc(i); 

end; 

if neg then 
n := -n; 
atoi := n; 
end; 

{ End of File ) 


STAMP OUT 
LISTING 
ERRORS! 

Windows/DOS Developer's Journal 
magazine code listings are already on 
disk. 

Send us $5. We'll send you the code. 
Ask for the code by issue number. 

To order, call or write: 

Windows/DOS Developer's Journal 
1601 W. 23rd. St., Ste. 200 
P.O. Box 3127 
Lawrence, KS 66046-0127 
(913) 841-1631 


The elements of the set need not be listed in any par¬ 
ticular order, so that both 

[4..8, 2] 

[6..8, 2, 4..5] 

have the same value. An element may also be specified more 
than once without affecting the value of the set, so that 

[6..8, 2, 4..6, 8] 

has the same value as the previous two sets, although 6 and 
8 appear twice inside the brackets. 

A set can contain values of almost any ordinal type. (In 
Pascal, an ordinal type is any type whose underlying repre¬ 
sentation is an integer value, such as integer, char, boolean-, 
an enumeration; or a subrange of any of the preceding. The 
integer value is obtained by applying the predefined ord func¬ 
tion - hence, the name ordinal type.) Thus, for example 

['a 1 , 'e\ M*. 'o', V, 'y'] 

is a set of characters containing the lower-case vowels in 
English. Given the enumerated type 

type 

day = (SUN, HON, TUE, WED, THU, FRI, SAT); 
then 

[MON.. FRI] 

is the set of weekdays. 

Empty brackets, [ ], denote the empty set. 

Pascal implementations may, and usually ,do, impose a 
limit on the size or range of values for sets. In Turbo Pascal 
and QuickPascal, the elements in a set must have ordinal 
values in the range 0 to 255, inclusive. Thus, a set cannot hold 
more than 256 elements. TopSpeed Modula-2 is considerably 
more generous. It allows elements to have ordinal values in 
the range 0 to 65535. 

Testing Membership 

The most commonly used set operation in Pascal tests an 
element for membership in a constant set with the in 
operator, in is a binary operator that returns a boolean - 
TRUE if the left operand is an element in the right operand, 
and FALSE otherwise. The right operand must be a set, and 
the left operand's type must have the base type of that set 
For example, 

d in [MON..FRI] 

is TRUE if day d is a weekday, and 
c in ['O'..'9'] 

is TRUE if character c is a decimal digit 

Listing 1 shows a common, practical use for the in 
operator. The listing contains a Pascal version of the standard 
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Listing 2 (map.pas) 


{* 

* map.pas - color a map 
*} 

{$ I readid.pas } 
const 

REGION_MAX = 255; 

type 

region = O..REGION_MAX; 

region_set = set of region; 

color = (RED, BLUE, GREEN, YELLOW); 

color_image_array = array [color] of string[6]; 

const 

C0L0R_MIN = RED; 

COLOR_MAX = YELLOW; 

color_image : color_image_array = 

('RED', 'BLUE', 'GREEN', 'YELLOW'); 

NAME_MAX = 3; 

var 

name : array [region] of string[NAME_MAX]; 
adjacent : array [region] of region_set; 
last_region : integer; 
colored : array [color] of region_set; 

procedure init_map; 
var 

r : region; 
c : color; 
begin 

for r := 0 to REGION_MAX do 
begin 

name[r] := ''; 
adjacent[r] := [ ]; 
end; 

last_region := -1; 
for c := C0L0R_MIN to C0L0R_MAX do 
colored[c] := [ ]; 

end; 

procedure dump_map; 
var 

ri, rj : region; 
begin 

for ri := 0 to last_region do 
begin 

write(name[ri]:NAME_MAX); 
for rj := 0 to last_region do 
if rj in adjacent[ri] then 

writeC ', name[rj] :NAME_MAX); 
writeln; 

end; 

end; 


STOP 


...ERRORS! 


End your listing errors by subscribing to 

Windows/DOS Developer’s Journal 

code listings on disk. 

...HIGHER 
PRODUCTIVITY! 



Save hours of typing in long code listings 
and make better use of your time. 



Call 913-841-1631 TODAY! 

For only $30* you’ll receive 12 disks 
(one per issue) of Windows/DOS 
Developer’s Journal listings. You’ll 
save 50% off the price of buying the 
disks individually! 

If you don’t already subscribe to Win¬ 
dows/DOS Developer’s Journal- 
order both the magazine and disk for 
$59* 

Subscriptions must be prepaid and 
are available on 5.25" or 3.5" 

MS-DOS format only. 


WindowsyPOS 

□ DEVELOPER’S JOURNAL 

1601 W. 23rd. St., Ste. 200 
P.O. Box 3217 
Lawrence, KS 66046-0127 


•foreign prices vary (call for details) 
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Listing 2 — Cont’d 

function region_number(var s : string) : integer; 
var 

r : region; 
begin 

for r := 0 to last_region do 
if s = name[r] then 
begi n 

region_number := r; 

exit; 

end; 

inc(last_region); 
if last_region > REGION_MAX then 
begin 

writeln('too many countries'); 

halt; 

end; 

name[last_region] := s; 
region_number := last_region; 
end; 

procedure readjnap; 
var 

ri, rj : region; 
s : string; 
begin 

while not seekeof do 
begin 

read_id(input, s); 
ri := region_number(s); 
while not seekeoln do 
begin 

read_id(input, s); 
rj := regionjiumber(s); 
adjacent[ri] := adjacent[ri] + [rj]; 
adjacent[rj] := adjacent[rj] + [ri]; 
end; 
readln; 
end; 

end; 

procedure writejnap; 
var 

r : region; 
c : color; 
begin 

for r := 0 to last_region do 
begin 

write (name [r] :NAME_MAX, 1 '); 
for c := C0L0R_MIN to C0L0R_MAX do 
if r in colored[c] then 
write(color_image[c]); 

writeln; 

end; 

end; 

function try_coloring(r : region) : boolean; 
var 

c : color; 
begin 

for c ;= C0L0R_MIN to C0L0R_MAX do 

if adjacent[r] * colored[c] = [ ] then 
begin 

colored[c] := colored[c] + [r]; 


C atoi function, presented in an earlier column[1], atoi com¬ 
putes the integer value represented by the sequence of 
decimal digits in a character string. The first uhile loop in 
Listing 1 skips leading whitespace in the string. SPACES is a 
symbolic constant defined as 

const 

SPACES = [' HT, CR]; 

and is the set containing a space, a tab, and a carriage return. 
(The program defines HT and CR as character constants.) The 
second loop scans the digits in the string and stops when it 
reaches the end of the string or runs out of digits. 

The in operator, along with the relational operators =, <, 
<=, etc., has the lowest precedence of all. For this reason, it's 
necessary to put parentheses around any in expression that's 
part of a larger expression, as in Listing 1, 

Use the not operator to test that an element is not in a 
set, as in 

if not (c in ['O'..'9']) then 

Forgetting the parentheses around the in expression is a 
common error, even for seasoned Pascal programmers. 
Without the parentheses, the operators group as 

if (not c) in ['O'..'9'] then 

which produces a compile error because not cannot operate 
on characters. In fact, in standard Pascal, 

not e in s 

produces a compile error except when e is a boolean and s 
is a set of boolean. 

In Turbo Pascal and QuickPascal, not (as well as and and 
or) also applies to integer operands. Thus, if i is an integer, 
then 

not i in [1, 3, 5] 

compiles without error in either Pascal dialect Whether it 
produces the desired result is another matter. 

Set Variables And Types 

In addition to the set constants shown above, set variables 
and types can also be declared. For example, a variable 
days_worked declared as 

var 

days_worked : set of day; 

can hold a set of days (where day is the previously defined 
enumeration). The identifier after "set of” is the base type of 
the set It can specify any ordinal type whose values fall 
within the range of set element values. 
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For example, Turbo Pascal allows set element values be¬ 
tween 0 and 255. Thus, boolean, byte (an unsigned eight-bit 
integer), and char can be base types, as can any enumerated 
type with no more than 256 values, integer cannot be a 
base type because there are more than 256 integers. How¬ 
ever, a base type can be a subrange, such as 

var 

small_set : set of 1..10; 

As noted earlier, TopSpeed Modula-2 allows a wider range 
for set element values. Thus, it lets you use CARDINAL (an 
unsigned 16-bit integer) as a set's base type. 

Pascal insists that the type of a formal parameter must be 
a named type. Thus, if you need to pass days_worked as a 
function argument, you must define a type name like 

type 

day_set = set of day; 

and declare days_worked and the function heading in terms 
of day_set: 

var 

days_worked : day_set; 

function is_overworked(d : day_set) 

: boolean; 


Listing 2 — Cont’d 


if (r >= last_region) 
or try_coloring(r + 1) then 
begin 

try_coloring := TRUE; 

exi t; 

end; 

wri tel n ( 1 backtracki ng... 1 ); 
colored[c] := colored[c] - [r]; 
end; 

try_coloring := FALSE; 
end; 

begin 

initjnap; 

readjnap; 

if try_coloring(0) then 
writejnap 

else 

writeln('no solution'); 

end. 

{ End of File } 


ELIMINATE BUGS! 



C is radically 
different from 
other languages — it's trickier 
to use, harder to learn, and much 
less forgiving. But worst of all, it’s 
impossible to debug with methods 
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SaveCanvas Version 1.0 $30.00 
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You must also give a name to the set 
type if you want to declare a pointer to 
it, as in 

var 

p : ~day_set; 

Set Operations 

In addition to the in operator, Pas¬ 
cal provides several other predefined 
operations on sets, such as assignment, 
comparison, and the usual mathemati¬ 
cal operations union, intersection, and 
difference. Table 1 summarizes Pascal’s 
set operators. The following examples 


demonstrate some of these operations. 
Suppose that class_days and 
work_days are variables of type 
day_set, initialized by 

class_days := [MON, WED, FRI]; 
workdays := [MON, SAT, SUN]; 

then 

class_days + work_days 

yields the set [SUN, MON, WED, FRI, SAT], 

class_days * work_days 


yields [MON], and 

[SUN..SAT] - work_days 
yields [TUE, WED, THU, FRI]. 

in Pascal, adding an element to a set 
is a special case of the union operator. 
For example, 

ciass_days := class_days + [TUE]; 

adds the element TUE to class_days. 
Both operands of a union must be sets. 
Therefore, you must convert day TUE 
to a set of day by enclosing it in square 
brackets before applying the union. 

The value(s) inside a set constructor 
need not be constant(s). For example, 



Table 1 

In the following, S and T are set expressions of the same type, and x is an 
expression of the base type of S. 

Assignment 

S:=T 

copies the value of T to S 

Mathematical 

S + T 

S * T 

S - T 

(union) yields the set of elements in either S or T 
(intersection) yields the set of elements in both S and T 
(difference) yields the set of elements in S but not in T 

Relational 

x in S 

S = T 

SOT 

S <= T 

S >= T 

(membership) is TRUE if x is a member of S 

(equality) is TRUE if S and T contain exactly the same elements 

(inequality) is TRUE if not (S = T) 

(subset) is TRUE is S is a subset of T, that is, if every element in s 
is also a member of T 

(superset) is TRUE if S is a superset of T, that is, if T <= S 

Set Operators in Pascal 


Listing 3 


AL 

AR 

GA AL 
IL 

KY IL 

MS AL AR 

MO AR IL KY 

TN MO AL AR MS GA KY 

VA KY TN 


var 

d : day; 

class_days : day_set; 

class_days := class_days + [d]; 

adds the value of the variable d to 
class_days. 

Removing an element from a set is a 
special case of the difference operator. 
For example, 

work_days := work_days - [SAT]; 

removes the element SAT from 
work_days. Again, note that SAT must 
be converted to a set before the dif¬ 
ference operator is applied. 

Modula-2 provides all of the set 
operators from Pascal plus one more, 
symmetric difference. The symmetric 
difference of two sets S and T is writ¬ 
ten as 5 / T, and yields the set of ele¬ 
ments in S or T but not both. Modula-2 
also provides two predefined functions, 
incl and excl. incl(S, x) adds ele¬ 
ment x to set S, and excl(S, x) 
removes element x from set S. 

Applying Sets 

Welsh and Elder [2] provide an ex¬ 
cellent example of a practical use for 
sets, coloring a map. A map of land 
may contain many regions, such as 
countries, states, or provinces, each of 
which is colored to highlight its boun¬ 
daries. The problem is to color the 
regions so that no two adjacent regions 
have the same color. Only four colors 
are required, (a team at the Univ. of Il¬ 
linois proved this long-standing conjec¬ 
ture just a few years ago). Listing 2 
shows our solution to the problem writ¬ 
ten in Turbo Pascal (also QuickPascal), 
based on Welsh and Elder's. 

The input to the program is a se¬ 
quence of text lines, as shown in the 
sample input in Listing 3. Each line con¬ 
tains the name of a region followed by 
zero or be names of other regions that 
share a border with the first region, (in 
Listing 3, the region names are US Post¬ 
al abbreviations for states). For example, 
the line 

MS AL AR 
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indicates that MS is adjacent to AL and 
AR. The data entry for AL need not in¬ 
clude MS because the adjacency 
relationship is symmetric, in other 
words, if MS borders AL, then AL auto¬ 
matically borders MS. A given region can 
be the first name on more than one 
line, but a given region need not appear 
at the beginning of any line. 

If the program successfully colors 
the map, it writes a list of the region 
names and their corresponding colors. If 
the program cannot color the map, it so 
notes. (Using four colors, the program 
fails only if the data is inconsistent; 
Using fewer colors, the program might 
fail because the coloring is impossible.) 

The map coloring program in Listing 
2 represents the input in the following 
data structures: 

var 

name : array [region] of 
string[NAME_MAX]; 

adjacent : array [region] of 
region_set; 

last_region : integer; 

The program stores each region 
name in name[r]. The index r is called 
the region number. The program as¬ 
signs region numbers in order as the 
region names appear in the input. 
last_region is the highest region 
number. Function region_number con¬ 
verts region names to region numbers, 
assigning new region numbers as 
needed. 

For each region number r, ad¬ 
jacent [r] is the set of region numbers 
for regions that share a border with 
region r. In the sample data KY is region 
number 4 (region numbers start at 
zero); after all the input is read, ad¬ 
jacent^] is the set [3, 6, 7, 8] 
representing the set of states {IL, MO, 
TN, VA). 

Procedure init_map initializes all the 
sets in the adjacent array to the empty 
set. Procedure readjnap fills in the 
array. In readjnap, ri is the region 
number of the first region name on the 
current input line, and rj is the region 
number of another region adjacent to 
ri. The statement 

adjacent[ri] := adjacent[ri] + [rj]; 


adds rj to the bordering regions of ri, 
and 

adjacent[rj] := adjacent[rj] + [ri]; 

adds ri to the bordering regions of rj. 
This guarantees the symmetry of the 
relationship “ri borders rj.” 

readjnap uses the function read_id 
to read each region name. read_id is 
defined in a separate file, read id. pas, 
that’s included at the beginning of List¬ 
ing 3 using the compiler directive 

($1 readid.pas } 

read_id, presented in an earlier 
column[3], uses the in operator to scan 
the input characters. 

The function dump_map is a diagnos¬ 
tic function for verifying the input. For 
each region number r, it displays 

name[r] and adjacent[r], translating 

the region numbers in adjacent[r] 
back into region names. Pascal does not 
have a way to say 

for each element x in set S do 
something with x; 

You must write it as 

for each element x in the base 
type of S do 

if x in S then 

something with x; 

This is the nature of the inner loop in 
dumpjnap. 

colored is another array of sets, one 
for each color, declared as-. 

var 

colored : array [color] of 
region_set; 

colored[c] is the set of countries 
painted in color c. These sets are initial¬ 
ly empty. If the program finishes suc¬ 
cessfully, every region number should 
appear exactly once somewhere among 
these sets. In other words, the union of 
all the sets in the colored array will be 
the set [0. .last_region], but the in¬ 
tersection of any two sets will be 
empty. 
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Function try_coloring colors the map using a recursive 
backtracking (trial and error) algorithm. With each call 
try_coloring(r) attempts to find colors for regions num¬ 
bered r and above. Specifically, try_coloring(r) picks a color 
for r, and then calls try_coloring(r+l) to color the rest of 
the regions. 

try_coloring(r+l) returns TRUE if it successfully colors all 
the remaining regions. If try_coloring(r+l) returns TRUE, 
then try_coloring(r) also returns TRUE. Otherwise, 
try_coloring(r) picks a different color for region r, and calls 
try_coloring(r+l) again. If try_coloring(r) runs out of 
colors, then it returns FALSE in the hope that try_color- 
ing(r-l) can find a different color for region r-i, and call 
try_coloring(r) again. 

try_coloring uses the following code to select a color for 
region r: 

for c := C0L0R_MIN to C0L0R_MAX do 

if adjacent[r] * colored[c] = [ ] then 


adjacent[r] is the set of regions adjacent to r and 
colored[c] is the set of regions already painted with color c. 
Thus, the intersection of these two sets is the set of regions 
adjacent to r with color c. If this set is empty, then region r 
can be colored c. try_coloring tentatively colors region r by 
adding it to the set colored[c] using 
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colored[c] := colored[c] + [r]; 

and then tries coloring the rest of the map. If the recursive 
call returns FALSE, then try_coloring “uncolors” region r by 
removing it from colored[c] using 

colored[c] := colored[c] - [r]; 

and iterates to find another possible color. 

All of the loops of the form “for each color do" use the 
constants C0L0R_MIN and C0L0R_MAX rather than RED (the 
first color) and YELL0U (the last color). This simplifies changing 
the actual coZors[4]. 

The sample data in Listing 3 describes a map that needs 
only three colors and can be colored with four colors without 
backtracking. To make the program backtrack, reduce the 
number of colors by setting C0L0R_MAX to GREEN. Even with 
only three colors, the sample data can be rearranged to 
eliminate the backtracking (we deliberately arranged that data 
so the program would backtrack when using only three 
colors). 

More to Come 

Using sets to solve the map coloring problem leads to a 
straightforward solution. If you know of other ways to solve 
the problem without using sets, we invite you to send them 
to us. You may find, however, that other solutions that don’t 
appear to involve set types actually use set types in disguise. 

The next part of this series on sets will look at how Pascal 
and Modula-2 implement built-in set types, and how to add 
set types to languages that don't have them. □ 
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Little Big LAN 

John 0. Foster 


LBL is the acronym for Little Big LAN, 
a set of software programs that imple¬ 
ment a peer-to-peer local area network 
for DOS-based PCs. LBL is from Informa¬ 
tion Modes, the maker of The $25 Net¬ 
work (see sidebar). LBL uses a combina¬ 
tion of device drivers and TSRs to pro¬ 
vide access to remote drives as though 
they were local drives. Two key fea¬ 
tures distinguish LBL from traditional 
LANs: it can communicate via a variety 
of methods that are cheaper than 
Ethernet adapters and it costs only $75 
(that is per network, not per node). This 
article is based on my experience using 
the beta version of LBL 

Traditional LANs require hardware 
adapters, typically Ethernet cards. LBL 
allows you to use Ethernet or ARCnet 
adapters, standard serial ports (COMx), 
parallel ports (LPTx), or even modems 
(for slow, but long-distance LANs). You 
can construct a network that uses any 
combination of these interfaces. The 
network drivers require 30Kb to 40Kb of 
memory (depending upon how you 
configure them) and you can load them 
into upper memory to conserve system 


RAM. Even with CD-ROM extensions, I 
still have 625Kb of system RAM. 

As a satisfied user of Information 
Modes’ original product. The $25 Net¬ 
work, I immediately volunteered to 
beta test the new LBL The prospect of 
being one of the first at anything new 
is enticing, and in this case, I have been 
well rewarded. With any complex 
software package in development, one 
expects to encounter serious problems, 
but I found myself using the beta LBL 
daily right away. 

My first installation used the serial 
ports, but I soon located a source for 
inexpensive ARCnet cards and began to 
upgrade rapidly. ARCnet (Attached 
Resource Computer network, developed 
by Datapoint) is a network topology 
that runs at 2.5 Mbps. That pace is slow 
compared to Ethernet's 10 Mbs, but 
quite fast compared to using serial or 
parallel ports. I can copy a 100Kb file in 
about four seconds across ARCnet. 
ARCnet cards from mail-order houses 
run as low as $50 per card and the 
necessary coaxial cables cost about $1 
per foot (ARCnet cards can drive up to 
2000 feet of cable without a repeater). 


Features 

■ Product: Little Big LAN 

■ Price: $75 per network 

(Registered owners of The $25 
Network receive a $25 dis¬ 
count) 

A peer-to-peer network. The in¬ 
itial release supports ARCnet, 
serial ports, and parallel ports. 
Future releases will support 
Ethernet and modems. 

■ Product: The $25 Network 

■ Price: $25 per network (You 
can also purchase cables, $15 
for a 104foot cable and $25 
for each additional foot) 

Software for networking two or 
three PCs via serial ports. Each 
PC can access all the drives 
(even floppy drives) and printers 
on the other PCs. 

Information Modes 
P.O. Drawer F. 

Denton, TX 76202 

(817) 387-3339 Tech support 

(800) 628-7992 Orders only 


John Foster is a programmer/author for Annabooks, where he specializes in embedded systems and PC-compatible program¬ 
ming. You mag contact him by mail at Annabooks, 12145 Alta Carmel Court, Ste. 250, San Diego, CA 92128, or by phone at 
1-800-462-1042. 












The $25 Network 


Little Big LAN is a descendant of Information Modes' 
first product, The $25 Network, an inexpensive and 
long-lived software product for networking two or 
three computers together via serial ports. The package 
includes a floppy containing the networking software 
and utilities, and a small manual. You can either buy 
or build the requisite null modem cables, or obtain 
them from Information Modes ($15.00 for a 10-foot 
cable, $.25 for each additional foot). 

The basic configuration consists of two computers 
connected via one serial port in each. You can con¬ 
figure the network software so each PC can access 
every drive (even floppy drives) and printer on the 
other PC. An alternative three-PC configuration uses 
one PC with two serial ports as a hub connecting two 
other PC. This is a handy solution for a two-person of¬ 
fice that needs to share a single printer connected to a 
third PC. 

Utilities 

The $25 Network includes a variety of utilities, 
some for diagnostics during installation and some for 
everyday use. FIXCOM restores the network to opera¬ 
tion after some other program has used the serial port. 
For example, if you use an A-B switch to switch be¬ 
tween the network and a modem on a single serial 
port, a program that uses the modem switch may not 
reset the port upon exiting. Simply invoking FIXCOM in 
that situation restores the serial port so you can switch 
back to using the network. 

NCON.SYS is a device driver that allows remote key¬ 
board control of a PC. The driver can accept keyboard 
input from a remote node of the network and insert 
the input into the local keyboard buffer. The result is 
as though you had remote control over the PC. 

NETALIVE is a handy way to check the status of the 
network. It sets the DOS error flag, so you can use it in 
batch files. Suppose, as in the previous example, you 
are using an A-B switch to share a single port between 
a modem and the network. You might use NETALIVE to 
remind you to switch the A-B switch by creating a 
batch file like: 

netalive 

if error)evel 1 goto NONET 
pause "Please switch AB switch" 

:NONET 
procomm 


The package also includes a print spooler, a device 
driver to prevent simultaneous printing on the same 
printer from two different nodes, and a utility for 
synchronizing system clocks across the network. 

Restrictions 

The main restriction is speed. Since the serial port is 
slow (115 Kbaud or worse), the network is slow. Unlike 
a network card, a serial port requires software to 
handle most of the work of communications; if a 
remote node is performing reading or writing a large 
file on your PC, you will notice markedly poorer 
response in whatever application you are running at 
the time. As a substitute for copying data onto and off 
of floppies, however, the serial port speed is quite ac¬ 
ceptable. Another serial port limitation is distance, 
since long cable lengths can cause transmission 
problems. You can expect your serial port to reliably 
drive up to about 80 feet of cable. 

The network allows you to access remote printers 
as well as remote drives. To do this, the network takes 
some pains to convince software that a local printer 
actually exists. Unfortunately, some programs are too 
aggressive in their printer interaction. For example, 
Microsoft Word prints across the network just fine, but 
Quicken insists that the printer isn’t ready. 

The network works well with Windows in enhanced 
mode, but some users report problems using it with 
standard mode. Information Modes is still investigating 
this problem. 

Although the network can access hard drives and 
floppy drives on the remote machine, you cannot use 
it to access CD-ROM drives. The network also does not 
support file and record locking, but does provide some 
software and documentation to help you roll your 
own. Little Big LAN removes most of these restrictions 
and can provide improved performance even if you 
stick to using serial ports. For $25, you don’t get a lot 
of coddling; if you are not comfortable stringing cables 
and if seeing “BACK UP YOUR HARD DISK FIRST” in 
documentation makes you nervous, this package is not 
for you. 

Summary 

Full-fledged, high-speed networks are still too ex¬ 
pensive for most home PCs and even for many small 
businesses. The $25 Network provides a stable, inex¬ 
pensive solution for low-traffic situations. □ 
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I soon had all my six clones networked and, most sig¬ 
nificantly, began to think of the computer resources as com¬ 
munal instead of individual. After enjoying the capability to 
distribute programs around the existing hard drives, I was able 
to think of each node in terms of “total” disk space on the 
network, rather than the disk space on any one node. Moving 
files from one node to another as needed became a simple 
copy operation, and organizing nodes according to their func¬ 
tion was intuitive and easy. Now that I operate in a network 
environment, I fear to think of going back to a standalone 
mode of operation. 

In my period of beta testing (approximately six months), I 
lost data only once, in a case where I was working on some 
text files with a text editor that used file FCBs instead of hand¬ 
les. At that point, FCB support hadn't been implemented in 
LBL, but Information Modes rapidly updated LBL, and data 
reliability was restored. I have operated LBL with MS-DOS 3.31, 
4.01, 5, DR-DOS 5, and Windows 3.0, booting from floppy, hard, 
and solid-state disk, running a variety of applications 
programs. One node runs a BBS program, and the convenience 
of being able to access its hard drive during operation makes 
on-line adjustments utter simplicity. 

I do most of my software development on my develop¬ 
ment machine, then test on my target machine; I use LBL to 
move the program I am testing into the target, bypassing pre¬ 
vious prom-burning stages and saving lots of time and incon¬ 
venience. Windows works well on LBL, as do most of my 
utilities (Norton, etc.) and the convenience of being able to do 
Jumbo tape backups across the network is immeasurable. Fur¬ 
ther, LBL allows me to distribute 360Kb, 720Kb, 1.2Mb and 
1.44Mb drives in the existing cabinetry, since all nodes can 
access them, and thus to avoid the expense of huge tower 
cases. 

Sharing printers is another advantage that should not be 
overlooked. As of this writing, Information Modes is still writ¬ 
ing the final version of the print spooler (it will be available by 
the time you read this). 

An outstanding feature of LBL is the option to operate with 
mixed hardware interfaces - a major advantage over some 
other popular peer-to-peer packages. I used this option to add 
a “guest” node stub to one of the ARCnet nodes by designat¬ 
ing a serial port that can temporarily connect to a guest 
machine and include it in the network. Since most machines 
have an existing serial port (which means the cover doesn't 
even have to come offl), I can include the guest machine by 
simply attaching a null modem cable, and booting up with a 
special floppy. Since one of the nodes contains a Jumbo tape 
backup, I can use it to back up the hard disk of the guest 
machine. Then I can repartition, reformat, and restore the 
guest machine's hard disk without wasting time with floppy 
disk backups. Consider this benefit next time you need to 
reformat a large hard drivel 

LBL uses two files to configure the network: a connection 
list and a drive redirection list. You can initialize these with 
the supplied configuration program and you can also configure 
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them dynamically on an installed net¬ 
work. LBL includes options to allow ab¬ 
solute sector operations (if enabled) on 
remote drives. Without this option, disk 
utilities and diagnostics that use INT 25 
cannot read or write remote drives. I 
leave these features disabled on the 
premise that if I am not permitted to 
do something I have no reason to do, it 
won’t happen. 

Information Modes' attractive pricing 
strategy might lead you to conclude 
that the low price means low value, 
and I admit that I was somewhat skep¬ 
tical when I ordered The $25 Network. I 
was quickly converted, however, and 
LBL has reinforced that conversion. 

If you are using The $25 Network, 
you may want to replace it with LBL, 
even if you do not plan to take ad¬ 
vantage of LBL’s ARCnet and Ethernet 
support. LBL can provide faster, 
smoother operation than The $25 Net¬ 
work, even in exactly the same 


hardware configurations. LBL works cor¬ 
rectly with CD-ROM drives and also sup¬ 
ports INT 21 file and record locking cor¬ 
rectly, whereas The $25 Network does 
not. Existing users of The $25 Network 
receive a $25 discount on LBL. 

As an embedded systems developer, 
I recognize that LBL has myriad uses for 
DOS-based embedded systems, where 
interconnection of platforms can 
simplify systems architecture. LBL’s 
flexibility in hardware interface support 
and simplicity of operation make it a 
natural for remote distributed systems, 
and when I advise customers of the ex¬ 
istence of LBL, they quickly recognize 
how their applications can be enhanced 
by networking. The bottom line is that 
if you have two or more computers, 
you definitely need a network, and if 
you do not want to spend thousands of 
dollars, Little Big LAN is probably the 
network you need. □ 
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New Products 

Industry-Related News & Announcements 


Distinct TCP/IP Adds VB And TP Support 

Distinct Corporation has released version 2.0A of the Dis¬ 
tinct TCP/IP Software Development Kit Distinct TCP/IP is com¬ 
patible with both Novell and Lan Manager and extends 
TCP/IP, RPC and NFS networking capabilities to Windows 
programmers. The package comes with three APIs in the 
form of DLLs: Berkeley Sockets, Remote Procedure Call (RPC), 
and Network Windows (NFS client). 

Version 2.0A adds support for Visual Basic and Turbo Pas¬ 
cal for Windows. The package includes Visual Basic declara¬ 
tions and Turbo Pascal import units that ease the task of 
interfacing with the Distinct TCP/IP DLL This release includes 
three Windows applications: NFS Manager, which mounts 
the NFS drive for Distinct TCP/IP applications, a network con¬ 



figuration utility that sets up the network interface card, and 
Network Monitor. Network Monitor contains utilities for 
monitoring the host communication and data transmission 
traffic, providing statistics on how many packets are trans¬ 
mitted and received, and providing error reporting. 

The package requires Windows (any mode), a network 
adapter card, Microsoft C or Visual Basic or Borland C++ or 
some other Windows development environment, and a 
remote host running TCP/IP. Distinct TCP/IP costs $495. For 
more information, contact Distinct Corporation, P.O. Box 
3410, Saratoga, CA 95070-1410, (408) 741-0781; FAX (408) 
741-0795. 


Information Architects Releases Banalyze V2.0 


Banalyze v2.0 is a rewritten version of Information 
Architect’s Bbug 1.0 program. Banalyze is a language-inde¬ 
pendent TSR that displays in a popup window all parameters 
passed to and returned from Btrieve. Banalyze consumes 
only 18Kb and allows Btrieve developers to dynamically 
debug their application’s Btrieve interface. Banalyze v2.0 can 
log screen information to an ASCII file for later analysis and 
filter Btrieve calls by file, operation, and error status. The pro¬ 
gram can store filters in a parameter file for re-use in future 
debugging sessions. 


Since Novell’s NetWare SQL and XQL developer kit uses 
Btrieve, Banalyze can also monitor and debug applications 
written with these SQL database managers. The package in¬ 
cludes a special parameter file to filter XQL dictionary calls 
so programmers can concentrate on data access calls. 
Banalyze 2.0 costs $99 and network licenses are available. 
For more information, contact Information Architects, 3130 
Pine Tree Road, Lansing, Ml 48911, (517) 887-8000; FAX 
(517) 887-2366. 


DataLIB Provides DOS And Windows Import/Export 


DatTel Communication Systems has released DataLIB, a 
set of libraries that can handle data import and export for a 
variety of ASCII, spreadsheet, and database file formats. 
DataLIB supports popular spreadsheet and database file for¬ 
mats, including Lotus 123 (.WKS and .WK1), Quattro (.WQK), 
Excel (versions 2 and 3 .XLS), dBASE (versions II, III, and IV, 
.DBF), ASCII (fixed- and variable-length records), Data Inter¬ 
change Format, and SYLK. DataLIB provides a single function 
interface for multiple file format access from any application 
or development system. 

DataLIB/Windows is a dynamic link library (DLL), so it 
works with most Windows applications, languages, and 
development systems, including C, C++, Turbo Pascal for Win¬ 


dows, ToolBook, Visual Basic, Smalltalk, Actor, and so on. 
DataLIB/DOS is a library that works with most C and C++ com¬ 
pilers, including Microsoft C, Borland C++, and Turbo C 
DataLIB/DOS source code is also portable to any ANSI C com¬ 
piler. 

DataLIB costs $395, which includes a royalty-free distribu¬ 
tion license. You can purchase source code and site licenses 
separately and a demo disk and sample programs are avail¬ 
able on request For more information, contact DatTei Com¬ 
munication Systems, Inc., 3508 Market Street; Suite 415, 
Philadelphia, PA 19104, (215) 564-5577; FAX (215) 243- 
3705. 
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ObjectGraphics Extends Turbo Pascal For Windows 


The Whitewater Group has announced ObjectGraphics, 
an object-oriented graphics library for Turbo Pascal for Win¬ 
dows (TPW). ObjectGraphics provides a high-level interface to 
Windows graphics and hides the low-level Windows 
graphics API. With ObjectGraphics, users can create and 
manipulate rendering tools such as pens, brushes, and 
textpens to control the appearance of graphic images. These 
tools allow the user to specify drawing attributes such as 
line styles, fill patterns, colors, fonts, drawing combinations, 
and more. 

ObjectGraphics is designed to be platform-independent 
and portable, providing a translation layer between applica¬ 


tion code and the target platform's graphics engine. The 
package includes ObjectDraw, a sample draw application. 
Written in Turbo Pascal, ObjectDraw uses ObjectGraphics to 
demonstrate graphics techniques and provide reusable code 
that developers can incorporate into their own applications. 

ObjectGraphics for TPW costs $195; source code costs an 
additional $195. For more information, contact The 
Whitewater Group, 1800 Ridge Avenue, Evanston, IL 
60201, (708) 328-3800; FAX (708) 328-9386. 


32-bit DOS Extender Supports DPMI 

Rational Systems, Inc, has released DOS/4G, a 32-bit DOS 
extender that supports the DOS Protected Mode Interface 
(DPMI) and is available without royalty fees. Using less than 
25Kb of real memory, DOS/4G allows users to run 32-bit ap¬ 
plications in protected mode under any DPMI-compliant 
operating system, such as Windows 3.0. DOS/4G provides a 
linear (non-segmented) addressing memory model and is 
also compatible with VCPI and XMS memory management 
standards. DOS/4G supports TSRs, including TSRs that con¬ 
tinue to run while Windows is running. 

DOS/4G comes with Virtual Memory Manager (VMM), a 
page-oriented facility that uses the 80386/486’s hardware 


paging facilities to automatically swap code and data to disk. 
VMM is compatible with DPMI. The product has been tested 
with a variety of Japanese computers, including the NEC 98- 
series and the Fujitsu FMR PCs. 

DOS/4G includes GLU/32, a 32-bit linker that is command¬ 
line compatible with the Microsoft linker. The package also 
contains a debugger that supports compilers that generate 
CodeView debugging information. DOS/4G costs from $5,000 
to $25,000, depending o.-i system configuration. For more in¬ 
formation, contact Rationed Systems, Inc, 220 No. Main St, 
Natick, MA 01760, (508) 653-6006; FAX (508) 655-2753. 


Block Island Updates Real-Time Toolkit 

Block Island Technologies has released version 3.1 of its 
Interwork Concurrent Programming Toolkit for PCs and com¬ 
patibles running DOS and for Unix workstations. The toolkit 
lets developers construct their applications as a set of 
cooperating, logically concurrent tasks. The package sup¬ 
ports a large number of tasks, limited only by available 
memory. The programmer can control the task scheduling 
policy and a variety of inter-task communication 
mechanisms, including locks, semaphores, mailboxes, and 
event variables. The new release contains refinements to op¬ 


timize real-time response and now provides ANSI C com¬ 
patible function calls. 

The DOS version of the toolkit is compatible with 
Microsoft C, Turbo C, Borland C++, Zortech C++, and Lattice C 
compilers. The product includes both large and small 
memory model versions for most compilers. The Concurrent 
Programming Toolkit costs $229 for the DOS version, $279 for 
the Xenix/286 version, and $369 for Unix versions. For more 
information, contact Block Island Technologies, 15455 NW 
Greenbrier Pkwy., Suite 210, Beaverton, OR 97006, (503) 
690-7181; FAX (503) 645-7732. 


Microsoft Releases QuickC For Windows 

QuickC for Windows is a new integrated Windows 
development environment from Microsoft Designed to help 
programmers new to Windows programming, QuickC for 
Windows includes the QuickWin library to help port existing 
DOS C applications and QuickCASEW to ease building user in¬ 
terfaces. The QuickWin library reduces porting time by sup¬ 
plying Windows versions of many DOS C functions. 
QuickCASE-W allows programmers to prototype and 
generate code for Windows user interfaces. You can hand- 
modify the code generated and still return to QuickCASEW 
to make further modifications to the user interface. 


The package includes an integrated Windows debugger 
and documentation for QuickC, the Windows API, the C lan¬ 
guage and runtime libraries. QuickC for Windows costs $199. 
Registered owners of Microsoft C v5.0 or higher, Microsoft 
QuickC v2.0 or higher, and Microsoft QuickC Compiler with 
QuickAssembler v2.01 or higher can upgrade to QuickC for 
Windows for $89.95. 

For more information, contact Microsoft Corporation, 
One Microsoft Way, Redmond, WA 98052-6399, (206) 882 
8080; FAX (206) 883-8101. 
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KnowledgeShop Builds Expert Decision Modules 


Decision System Software has released KnowledgeShop 
vl.O, a development tool that allows programmers and non¬ 
programmers to build, test, and embed knowledge-based 
decision making ability into their applications. Knowledge- 
Shop allows experts in any field to graphically construct 
decision modules that recreate their own analysis and 
reasoning techniques. After completing the decision 
modules, KnowledgeShop generates self-contained ANSI C 
source code that implements the expert’s decision module. 
Developers can then embed this source code into their ap¬ 
plications. 

KnowledgeShop's features include a graphical spread¬ 
sheet-like interface that requires no programming 
knowledge to use, unlimited reasoning network design 
flexibility, color-based debugging support, automatic verifica¬ 


tion of decision rule completeness, multiple conclusions 
within decision modules, full numeric and string functions, 
typeless attributes that hold mixed data types, bit-wise 
operators, certainty factors, and I/O to sensors, actuators or 
controllers. 

KnowledgeShop costs $295, is royalty free, and requires 
a PC or compatible with 640Kb of memory, a hard disk, and 
a CGA or better color monitor. The source code it generates 
is portable to any platform that supports a C compiler. The 
resulting code can process 3,000 rules per second on a 
20MHz 80386. The program comes with example decision 
modules, a demonstration and tutorial, and a 250-page 
user’s guide. For more information, contact Decision System 
Software, 160 West Street, Cromwell, CT 06416, (203) 632- 
7570; FAX (203) 635-3839. 


Periscope Takes On Protected Mode 

The Periscope Company now supports protected-mode 
debugging with the release of Periscope/Remote for OS/2, 
Periscope/Remote for Windows, and The Periscope 32-Bit 
Toolkit All three debugging tools require a target computer 
connected to a host computer via a null-modem cable, with 
a dedicated serial port on each system. 

Periscope/Remote for OS/2 provides full-screen, source- 
level support for debugging Base and PM device drivers 
under OS/2 vl.2 or vl.3. Periscope/Remote for Windows 
provides full-screen, symbolic and source-level support for 
debugging virtual device drivers under Windows 3.x en¬ 
hanced mode. Like the OS/2 debugger, it runs in protection 
ring 0 and can coexist with an application (ring 3) debugger. 


The Periscope 32-Bit Toolkit allows developers of protected- 
mode environments such as operating systems, memory 
managers, and DOS extenders, to debug their code. 

Periscope/Remote for OS/2 costs $195 and requires DOS 
3.0 or later and Periscope 5.20 oh the host Peri¬ 
scope/Remote for Windows costs $195 and requires the 
new Periscope/32 software on the host and Windows 3.x in 
enhanced mode on the target The Periscope 32-Bit Toolkit 
costs $495 and requires a signed license agreement For 
more information, contact The Periscope Company, Inc., 
1197 Peachtree St, Plaza Level, Atlanta, GA 30361, (404) 
875-8080; FAX (404) 872-1973. 


Actor Update Includes SQL Support 

Whitewater has released Actor v4.0. Actor is an object- 
oriented language and development environment for Win¬ 
dows. This release introduces database-independent SQL 
libraries and DLLs for Paradox, Excel, SQL Server, dBASE, DB2, 
Oracle, and OS/2 Extended Edition. This version also supports 
safe multiple inheritance via a protocol process that auto¬ 
matically manages conflicts and prevents unintentional data 
corruption. Actor offers three types of browsers/editors and 
multiple procedures for navigating through class hierarchies. 

Actor is available as Actor 4.0 and Actor 4.0 Professional. 
The Professional version includes SQL libraries for dBASE, 


Excel, Paradox and ASCII, an upgraded ObjectGraphics library, 
and the Whitewater Resource Toolkit Actor 4.0 costs $249; 
Actor 4.0 Professional costs $495, You can upgrade from pre¬ 
vious Actor versions to Actor 4.0 or from previous Actor 
Professional versions to Actor Professional 4.0 for $75; 
upgrading from previous Actor versions to Actor 4.0 Profes¬ 
sional costs $195. A DLL for higher-end database access to 
DB2, Oracle, SQL Server and OS/2 Extended Edition costs 
$395. For more information, contact Whitewater, 1800 
Ridge Avenue, Evanston, IL 60201, (708) 328-3800; FAX 
(708) 328-9386. 


Borland Ships Resource Workshop For Windows 


Borland’s recent Windows development products have 
depended on the Whitewater Resource Toolkit to provide 
programmers with a Windows resource editing environ¬ 
ment Now Borland has released their own Resource 
Workshop, a Windows application for designing and cus¬ 
tomizing Windows resources - icons, dialog windows, fonts, 
and bitmap graphics. Resource Workshop supports editors 
for each of the Windows resource types and also facilities 
for creating user-defined resources. 

Besides the standard Windows 3.0 controls, Resource 
Workshop includes Borland Custom Controls, the software 
that provides the visual style of Borland’s Windows products. 
They include radio buttons and check boxes with the look of 


chiseled steel, push buttons that can include bitmap 
graphics and text, and dialog boxes with matted back¬ 
grounds to produce a three-dimensional effect 
Besides allowing programmers to design their 
application’s user interfaces, end users can use Resource 
Workshop to tailor Windows applications, since Resource 
Workshop can operate directly oh the resources in a com¬ 
piled Windows executable. Resource Workshop costs $49.95 
and is available direct from Borland. The package includes a 
free set of 64 icons. For more information, contact Borland 
International, Inc, 1800 Green Hills Road, P.O. Box 
660001, Scotts Valley, CA 95067-0001, (800) 331-0877. 
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Greenleaf Updates M akeForm 

Greenleaf MakeForm is a menu-driven form design tool 
for painting data entry screens compatible with Greenleaf 
DataWindows. After you paint the data entry screens, Make- 
Form stores the screen definitions in a resource file that 
DataWindows can read to create the form at runtime. Make- 
Form supports prototyping by allowing the forms designer to 
immediately execute the form under design and enter test 
data. After testing the form, you can immediately return to 
making changes in the form. You can also create an ASCII 
description of the form and write it to disk to print later. 


GX Text Handles Graphics-Mode Text 

GX Text is a new software package that allows 
developers to display bitmapped text in any graphics mode, 
as simply as in text mode. With GX Text, developers can dis¬ 
play text in a variety of font typestyles, using the GEM font 
file format The package includes over 1Mb of fonts, or you 
can also use internal ROM fonts. GX Text can load fonts into 
conventional or expanded memory and place fonts directly 
in a library or the program's .EXE file. You can also write text 
directly to a virtual buffer and then use GX Effects (a com¬ 
plementary Genus package) to write it or fade it to the 
screen. 

With GX Text, you can control foreground and back¬ 
ground colors, transparent text, bolding, underlining, fixed 


Greenleaf MakeForm 2.0 costs $249 and includes online, 
context-sensitive help, a reference manual, and a conversion 
utility that converts form files created by MakeForm vl.O. 
MakeForm 1.0 users can purchase an upgrade for $80 by call¬ 
ing Greenleaf Software, Inc For more information and a free 
demo disk, contact Greenleaf Software Inc., Bent Tree 
Tower Two - Suite 570,16470 Dallas Parkway, Dallas, TX 
75248, (800) 523-9830; FAX (214) 248-7830. 


and proportional spacing, intercharacter spacing, alignment 
and justification, and logical operations. A GRID feature al¬ 
lows you to use character column and row coordinates to 
position text The package also cindlues font rotation in 90 
degree increments and text clipping at the pixel level. 

GX Text supports all display modes for Hercules, CGA, 

EGA, VGA and Super VGA display adapters, and contains com¬ 
piler interfaces for C, Pascal, Basic, Fortran, Assembly, and 
Clipper. The package includes a graphical font editor for 
creating custom fonts. GX Text costs $149 and source code 
costs an additional $150. For more information, contact 
Genus Microprogramming, Inc., 2900 Wilcrest, Ste. 145, 
Houston, TX 77042, (713) 870-0737; FAX (713) 870-0288. 


Coprocessor Provides Transputer-Based Arrays 


Computer System Architects has released the SuperSet- 
Plus family of multi-user, transputer-based, parallel coproces¬ 
sor arrays. These engines contain from 16 to 256 nodes and 
can accomodate up to 16 users hosted on PCs or SUN 
workstations, directly connected or over a network. The 
SuperSetPlus operating system runs on a separate, dedicated 
processor, allowing individual users to allocate portions of 
the parallel array with no runtime overhead and no system 
interference. 

The SuperSetPlus is partitioned into 16 identical proces¬ 
sor clusters that can be grouped into larger configurations 
and then allocated to individual users. Individual users can 
repeatedly download code and debug or reset their allo¬ 
cated processors without interfering with the system or 


other concurrent users. Users can also use one of several 
transputer operating systems (such as Helios or Express) or 
work solely with the transputer's built-in multitasking 
process scheduler. 

A minimum SuperSetPlus configuration has 16 20MHz 
T425's, each with 256Kb of RAM, resulting in an aggregate 
performance of 160 MIPS and total memory of 4Mb. A maxi¬ 
mum configuration has 256 30MHz T800's, each with 32Mb 
of RAM, for 3,840 MIPS, nearly one billion FLOPS, and a total 
of eight billion bytes of memory. Prices for the SuperSetPlus 
start at $16,230. For more information, contact Lyle Bin¬ 
gham at Computer System Architects, 950 N. University 
Avenue, Provo, UT 84604, (801) 374-2300; FAX (801) 374- 
2306. 


Application Framework Augments Borland C++ 


Borland International, Inc is now shipping Borland C++ & 
Application Frameworks. The addition of Application 
Frameworks provides programmers with tools for creating 
user interfaces in both DOS and Windows. Application 
Frameworks consists of ObjectWindows for Windows and 
Turbo Vision for DOS. Application Frameworks contains full 
source code for both ObjectWindows and Turbo Vision. 

ObjectWindows provides a functioning Windows applica¬ 
tion that developers ran use as a template. You ran add win¬ 
dows, menus, dialogs, buttons, list boxes, edit fields and 
icons with ObjectWindows. Turbo Vision provides the same 
functionality in the DOS environment that ObjectWindows 
provides for Windows. Turbo Vision allows programmers to 


create a Windows-like user interface for their character¬ 
mode DOS applications. Turbo Vision is now also available 
with Turbo C++, Borland’s entry-level C and C++ compiler for 
DOS. 

Borland C++ & Application Frameworks costs $695. Turbo 
C++ & Turbo Vision costs $199.95 (add $69.95 for source 
code). Current Borland C++ users ran upgrade to Borland C++ 
& Application Frameworks for $199.95, upgrade to just 
ObjectWindows for $99.95, or upgrade to just Turbo Vision 
for $99.95. Current Turbo C++ users ran upgrade for $99.95. 
For more information, contact Borland International, Inc., 
1800 Green Hills Road, P.O. Box 660001, Scotts Valley, CA 
95067-0001, (800) 331-0877. 
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Readers' Forum 


We ask that letters with code listings be 
submitted in an ASCII text file on an MS- 
DOS formatted disk. Providing us an 
electronic copy of the code will prevent 
typographical errors that might resu/t 
from optical scanning or re-keyboarding. 


Dear Ron: 

I'd add a bit to your response to L 
Larison’s letter (TECH Specialist vol. 2, 
no. 6) on the new Readkey (for Turbo 
Pascal, TECH Specialist vol. 2, no. 4). 

In Mr. Larison's context, even more 
important than distinguishing Backspace 
from A H is that in the most frequent 
uses, i.e., testing for y/n, the qch (quick- 
Ch) is EXACTLY like the familiar ch from 
Read Key ... but there’s no need to 
check for #0, let alone flag it, or to 
make a second call to clear the function 
for its next use. The few lines of code 
left out each time will add up. 

The Wordstar workaround gets rid of 
the fkiboolean okay, but if you’re going 
to build a key identifier function around 
Readkey, truncating read ASCIIs at 127 
sounds risky to me, setting up blind 
spots. If nothing else, you abandon 
IBM’s character-based graphics. Or, if 
you use this only where such things 
don’t matter, then you’ve got to have 
two or three more for where ‘’other’’ 
things do matter. 

The more common workaround 
(staying out of assembly) has usually 
been to use intr($16, Regs), as I did in 
RdKey, and load up some kind of Key- 
Rec with whatever’s needed. All I’ve 
done in Rdkey is standardize that fch 
(FullCh : KeyRec), put all the information 
in it, give it the familiar TP “look and 
feel,” and throw in qch for turbo speed 
"optimizing” in everyday situations 
(even to allowing carelessness). 

But I’m adding Larison’s trick to the 
half-dozen I've got in my kit for those 
occasions when I’m putting source on 
the wind that’ll be seen by people who 
haven’t seen RdKey. 

Gene Fowler 
1432 Spruce Street 
Berkeley, CA 94709 


Dear Sir: 

I will be trying out your magazine 
and to start things off I have some 
questions I would like some help with. 

Question number one concerns DOS: 
How does DOS know that a particular 
sector is bad? Does it keep a record of 
bad sectors anywhere, or does it start a 
bad sector off with a particular value? 
How can I make DOS think that a good 
sector is bad? 

Question number two concerns ARC 
files: What is the theory behind com¬ 
pressing files to form an ARC file? I think 
that some compressing must be getting 
rid of white space, but there has to be 
a lot more to it than this. Since this 
question may be rather involved, 
maybe you could point me to some 
literature on the subject. 

I hope you can help me on these 
two questions, and I do look forward to 
receiving your magazine. I should be 
able to learn many new techniques, 
and just increase my knowledge about 
many different subjects. 

Lyle Hager 


Thanks for trying the magazine. You 
can mark a sector bad at different 
levels. For example, you can use inter¬ 
rupt 13h, function 05h to format a track 
and, in so doing, specify which sec¬ 
tors to mark as bad. At a higher level, 
DOS knows that a sector is bad be¬ 
cause FORMAT detected the problem 
and gave the corresponding File Al¬ 
location Table (FAT) entry a value of 
0xFF7 (or 0xFFF7 if it is a 16-bit FAT). 
You can make DOS think a good sec¬ 
tor is bad by marking the correspond¬ 
ing FAT entry. A single FAT entry may 
refer to a cluster of sectors, so you 
can only mark the entire cluster bad. 
Check out the discussion of the FAT in 
Ray Duncan's Advanced MS-DOS 
Programming. It should go without 
saying that if you write software that 
directly formats tracks or alters the 
FAT, plan on losing your disk a few 
times while you work out all the bugs. 


I have never seen the source to any 
ARC utility, but i think I grasp the basic 
strategy such programs use. Different 
compression schemes do a better or 
worse job, depending on the data file 
you hand them. For that reason, some 
archive utilities will try more than one 
strategy and pick the one that 
produces the most compression. 
Three good choices are: simple run- 
length encoding, Huffman encoding, 
and some adaptive encoding algo¬ 
rithm (such as Lempel-Zev). 

Compressing a file more than one 
way and picking the best method 
sounds very wasteful, but is not a bad 
choice in practice. It turns out that 
Huffman encoding requires two pas¬ 
ses over the input file anyway (one to 
create a table of character frequen¬ 
cies, the other to use that table to 
compress the data). So, you can do 
three things during a first pass over 
the data: create the Huffman diction¬ 
ary, create a compressed file using an 
adaptive scheme, and calculate how 
much repetition the data contains. At 
the end of that pass, you can make a 
very good decision about whether you 
already have the best compression 
(with the adaptive scheme) or whether 
you should make another pass to do 
run-length encoding or go ahead and 
use the Huffman dictionary. 

I haven’t read it, so I can’t recom¬ 
mend it, but I got a bingo card for a 
book about data compression that in¬ 
cludes a discussion of ARC-like 
utilities. The book is “Data Compres¬ 
sion, 3rd Edition, Techniques and Ap¬ 
plications, Hardware and Software 
Considerations", by Gilbert Held. The 
card does not have an ISBN number, 
but you can contact the publisher at 
Wiley Professional Books-By-Mail, 
John Wiley & Sons, Inc., P.O. Box 
6793, Dept. 063, One Wiley Drive, 
Somerset, NJ 08875-9977. -rib 


Dear Mr. Burk, 

I have several comments on “The 
Mathematical Programmer, Part 3” by 
Scott Ladd (June 91). 
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The tonearestO function is the most 
accurate and complete integer rounding 
routine in C that I have seen. Readers 
should remember to insert #include 
<math.h> at the top. 

The concept of using an allowable 
tolerance (epsilon) for terminating a 
converging iteration is good, but the 
magnitude of the numbers being com¬ 
pared must be considered. The ANSI- 
specified value recommended in the ar¬ 
ticle, FLT_EPS1L0N, represents the smal¬ 
lest possible change to 1.0F, not the 
smallest possible difference between 
two float values as stated. 

For solution values over a wide 
range, the proper value for epsilon 
should normally vary with the mag¬ 
nitude of the numbers being compared 
to achieve a given number of significant 
digits. The relative difference can be 
determined by dividing the difference 
by the old or new value of x before 
comparing, e.g.: 

fabs((xnew-xold)/xnew) <= tolerance. 

For some functions an absolute epsilon 
should be used for values of x near 
zero, resulting in two terminating condi¬ 
tions. I cannot agree with the author's 
recommendation of limited-precision 
rounding during intermediate calcula¬ 
tions. Each instance of such rounding 
adds more error to the final result A 
more accurate estimate is given by car¬ 
rying full precision throughout the cal¬ 
culations, then rounding to the desired 
precision on presentation (usually by a 
conversion format specification). The 
limited-precision rounding can indicate 
an estimate of accuracy, but not en¬ 
hance it. 

The randomd () function, written to 
return a random double value, converts 
from an int to a double after dividing, 
resulting in a return value of 0 for all 
calls (except when rando is rand_MAX)\ 

Assuming that a number is to be 
generated in the interval from 0.0 up to 
but excluding 1.0 (the normally desired 
case), the function should read 

#include <stdlib.h> 

double randomd (void) { 

return (rand() / (RANDJIAX + 1.0)) ; 

) 

Note the use of RANDJIAX, defined to be 
maximum value returned by rand(). 

Readers should be aware that the 
technique of setting a pointer to the 
address of an array minus one element 
to use for one-based indexing results in 
technically undefined behavior in ANSI 
C, although it is probably safe for most 
MS-DOS compilers. Another way, which 
is defined under ANSI C, is to define a 
macro for the indexing: 

Idefine fap(i) fa[(i)-l] 
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The programmer then uses parentheses 
rather than brackets for the subscripts 
(this may be an advantage for translat¬ 
ing Fortran codel). 

The IEEE 754 short real format for 
floating point has 23 signficant bits plus 
an implied leading 1 bit, resulting in 24 
bits of precision. This is equivalent to 24 
* log(2), approximately 7.2, decimal 
digits, rather than 6 as stated in the ar¬ 
ticle. Microsoft’s value of 7 for FLT_DIG is 
thus correct This can be demonstrated 
by reading values into a float (on a 
machine using IEEE short real format), 
then printing them. For each 7-digit test 
case that I tried (not all 9 million I) I got 
the exact number back. 

Thad Smith III 
T3 Systems 
2001 N. 75th St. 

Boulder, CO 80301 

I can’t find fault with any of your 
points, including the glaring bug in 
randomd (). How I missed that one, I'll 
never know. I would note that the fairly 
well-known book 8087 Applications 
and Programming for the IBM PC and 
Other PCs by Richard Startz states that 
the 8087 single-precision real has “6 
or 7" significant decimal digits. I can’t 
find any justification for that statement 
in the book, but perhaps one of our 
readers can shed light on that state¬ 
ment. We put the example listing you 
included on our code disk, it was a lit¬ 
tle long to print here. 

I was aware of the portability prob¬ 
lem you mention, but decided to let it 
slide since we are a PC-specific 
magazine. Personally, I try to avoid 
non-portable constructs even in 
machine-specific code; it's just a good 
habit to stay in. Of course, I also avoid 
macros that make C look like some 
other language. Thanks for your cor¬ 
rections and useful comments. 

While we are on the subject of 
floating-point, I would like to point out 
that we plan to do an issue on the 
theme of PC number crunching late 
next year. If you are an expert on float¬ 
ing-point coprocessors, or floating¬ 
point array board programming, or 
have other ideas related to PC number 
crunching, it’s not too soon to send in 
a proposal, -rib 


Dear Mr. Burk, 

Phil Weber’s article “Enhancing 
QuickBASIC's Capabilities With CALL IN- 
TERUPT” in your August 1991 issue was 
one of the most informative I’ve read in 
a long time. There are many of us BASIC 
programmers lurking out there who 
really make a living with this language, 
and any information that can help us 
add functionality and performance to 
our apps is well-appreciated. Many 
BASIC programmers are not aware that 


they can tap into DOS’s wealth of ser¬ 
vices with CALL INTERRUPT, and many 
who do know about this are often too 
intimidated to give it a try. Thanks to 
Phil for an article that does enough 
hand-holding to bring these folks up to 
speed. 

Susan Lemieux 
SMS Software 
Sierra Madre, CA 
Thanks for your response. We have 
more BASIC (and Visual BASIC) ar¬ 
ticles in the works, so stay tuned, -rib 


To the Editor: 

I saw your “call for papers" on Win¬ 
dows 3 topics and thought I'd write. 

I am working on an extremely 
simple method for porting DOS applica¬ 
tions written in C to Windows 3. The 
case study is my Pascal system (avail¬ 
able from Austin Code Works and writ¬ 
ten in Q that I am in the process of 
turning into something that resembles 
“Turbo Pascal for Windows” minus ob¬ 
jects - for now. The method permits 
applications to interact with Windows 
without causing damage and without 
major source code changes. 

A second application of this method 
would be to get the TEGLC toolkit to 
run under Windows so that TEGLC ap¬ 
plications that run under DOS can be 
ported to Windows with almost no ef¬ 
fort, and new TEGLC applications would 
use the TEGLC easytegl() environment 
as an intermediary to Windows in 
preference to writing Windows code 
directly. 

What I am saying is that I think that 
Windows 3 programming will become 
trivialized in the next year or so and 
that the majority of developers seduced 
by the promises of object-oriented 
programming for Windows will simply 
abandon the approach because it is 
laughable by comparison to easier-to- 
use methods. 

I’ll be interested to receive your 
authors’ guidelines sheet, and any com¬ 
ments you may care to add. 

Victor Schneider 
Schneider Software 
291 Summit Ave., Ste. 3 
Brighton, MA 02146 

P S. You are welcome to publish this 
letter as a provocation for discussion if 
you like. 

P. P. S. If you happen to know Earle J. 
Schweppe at the KU computer science 
department, say hello to him for me. 
We're old colleagues. 

Ease of porting has become the 
Holy Grail for a whole segment of Win¬ 
dows vendors. My personal belief is 
that there are significant limitations for 
any porting tool that are as immutable 
as the laws of thermodynamics. 
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If you are porting a program with a 
crude TTY user interface, you can ex¬ 
pect a high degree of automatic port¬ 
ing. The result, however, will be a pro¬ 
gram with a crude Windows user inter¬ 
face. Microsoft’s Fortran for Windows 
is an example of this. You simply can¬ 
not automate the porting of most 
programs that have elaborate user in¬ 
terfaces. 

For example, suppose five different 
companies have written their own 
elaborate user interfaces on top of a 
primitive package like Unix curses. 
How could an automatic porting tool 
figure out how each program decided 
to implement menus, messages, status 
bars, and so on? You could certainly 
just emulate curses under Windows, 
but I would hardly call that a success¬ 
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Hotice to Windows/DOS Subscribers 

Occasionally, Windows/DOS makes its 
mailing list available to vendors of 
products we think our readers will find in¬ 
teresting. Current subscribers receive free 
information in the mail from these ven¬ 
dors. If you prefer that your name not be 
used in these mailings, please let us 
know. Just copy or clip this form and send 
it with your name and address to: 
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ful port. The fundamental reason for 
having a GUI is so that the user only 
has to learn one user interface, not 
one user interface per application. 

I don’t mean to imply that automatic 
porting tools are not possible or use¬ 
ful. I just want to point out that the 
largest class of existing software can¬ 
not automatically be converted into 
Windows programs with slick, profes¬ 
sional, CUA-compliant user interfaces. 
You get what you pay for. 

I do have to flat-out disagree with 
the idea that object-oriented program¬ 
ming for Windows (or anything else) 
will be abandoned. If you are writing 
medium-to-small applications, sticking 
with straight procedural designs 
probably will not make you less com¬ 
petitive. Once you cross into the land 


of 100,000-line programs, however, 
object-oriented programming has too 
many potential (as in “not always real¬ 
ized”) benefits to ignore. At that size of 
program, I would use C++ instead of 
C just to have all the extra name 
spaces, if nothing else. 

Thanks for the interesting com¬ 
ments and for requesting the author 
guidelines. I look forward to seeing a 
Windows proposal from you and read¬ 
ing more about your porting techni¬ 
que. -rib 


RE: Disk Drive initiation, Greg Jennings' 
letter, June 1991 Issue 

The problem that Mr. Jennings 
described, and two readers tried to 
clear up is the result of the introduction 
of dual media drives for use with the 


EGAD 

Screen Print Package 

• Supports VGA, EGA, CGA, 
MGA displays up to 800x600 

• Select printout colors/gray 
tones; print any rectangular 
region; enlarge graphics 1-4 
times; many other features 

• Works with most printers 

• TSR (Shift-PrtSc) or call from 
your program. TSR is 9-15K. 

• Licensing available. 

$35.00 postpaid. Free catalog. 


LS Software 8139 E. Mawson, 
Mesa, AZ 85207 (602) 380-9175 

□ Request 124 on Reader Service Card □ 


PostScript Power 

PSPlot PostScrip t printer mana¬ 
ger. Converts HP-GL plots to Post¬ 
Script or EPS; plots lines any width or 
color. Has PostScript editor, font 
downloader and error display. Prints 
ASCII/FORTRAN files. Puts PC and 
MAC fonts in RAM or on printer disk. 
Works on networks. $175 

Double lJl> Booklet maker. Ideal for 
instruction manuals, reports. Accepts 
PostScript output files from Ventura, 
Sprint, PageMaker, WordStar, Interleaf, 
Manuscript, Word for Windows, etc. 

Save paper with duplex printing, even 
from non-duplex printers. $259 

Legend Communications, Inc. 

54 Rosedale Avenue West 
Brampton, ON, Canada L6X 1K1 

30 day guarantee 

(800)668-7077 (416)450-1010 

□ Request 191 on Reader Service Card □ 


UNIVERSAL 

Cross-Disassembler 


Missing source? Debugging? 
Upgrading an unsupported 
product? Then XDASM may be 
the solution. This unique MS- 
DOS based software disassembles 
programs for several types of 
microprocessors and 
microcontrollers. Creates an 
“Assembler Ready” source file 
from a Hex or Binary input file. Has configurable 
output to match assembler. Allows full control of 
disassembly using a separate TAG file. Assigns label 
names, provides instruction line detail, inserts 
assembler directives!, deblocks source code into 
subroutines and generates multiple cross-reference lists. 
Processor families include: 1802, 4004, 6301, 65C02, 
6800, 6805, 6809, 68HC11. 7810, 8048, 8051, 8085, 

8096, COP400 800, Z8, Z80, Z180 plus others. Dual 
media diskettes and manual, $249. CROSS-16, the 
universal Meta-Assembler, available for $99. 

Check MO PO COD. 

Data Sync Engineering 

P.O. Box 146 

East Stroudsburg, PA 18301 

Tel (717) 421-1977 Fax (717) 421-9095 

□ Request 161 on Reader Service Card □ 


PostScript TSRs — Under 9K 

PSFX TSR prints PostScript out¬ 
put, just as formatted for Epson or IBM 
ProPrinter. See graphics, fonts, accents 
and boxes! Choose portrait or landscape, 
sizes up to 1 lxl7. Print one or two 
pages per sheet. Use with databases, 
accounting, RrtSc key. $85 

PSFXnet Novell NetWare version 
adds banner pages. Keeps statistics on 
pages printed by each userlD. $99 

EPScreen Captures PC screens as 
tiny Encapsulated PostScript (EPS) 
files (3K), frames & TIFF optional. 
Illustrations for manuals. Font included. 
Color files less than 10 K. $95 

Legend Communications, Inc. 

54 Rosedale Avenue West 
Brampton. ON, Canada L6X 1K1 
30 day guarantee 

(800)668-7077 (416)450-1010 

□ Request 157 on Reader Service Card □ 
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AT. Prior to the AT, there was only one 
density, and DOS 2.xx did not have to 
know which type of disk was in the 
drive. Starting with DOS 3.00, the sys¬ 
tem had to know if a 360K, or a 1.2 
meg was in the drive. This was handled 
by the operating system trying to read 
the disk, and switching to the other 
density and retrying if there was an 
error. This is fine if there is a formatted 
disk in the drive, but what happens 
during formatting when the density is 
unknown? 

The answer is simple: starting with 
DOS 3.00, and expanded in later ver¬ 
sions is a way to force the drive to the 
desired density using I NT 13H, AH=17H. 
If AL=01H, then disk is a 360K in a 
regular drive-, AL=02H, then disk is a 
360K in a high density drive; AL=03H, 


then the disk is a 1.2 meg in a high 
density drive. 

DOS 3.2x added AL=04H for a 720K, 
3.5 inch drive, and DOS 3.3x added 
AL=05H and 06H for 720K and 1.44meg 
in a high density 3.5-inch drive. 

I ran into this problem a couple of 
years ago when I wrote a direct disk 
copy program in Turbo Pascal for 
recovering damaged disks. Until I found 
out the problem, I too was doing a DIR 
on a good high density disk before 
using the recovery program. A copy of 
the program is included on this disk as 
an example of the usage. 

Charles J. Billwiller 
2313B Sierra Madre Court 
Rancho Cordova, CA 95670 

Thanks for the answer. We put your 
code on the code disk, -rib 


Dear Ron: 

I enjoyed your editorial about Hun¬ 
garian notation in the October issue of 
TECH Specialist I agree that Hungarian 
notation tends more to obscure the 
meaning of variables than to clarify 
them. Hungarian notation does little to 
prevent inadvertent type conversions 
either. Most compilers and lint utilities 
work better at finding misused vari¬ 
ables then Hungarian notation. 

I have found one situation where 
adding a prefix to a variable name does 
add meaning, readability and has 
helped me find problems. That situation 
is to encode the scope of a variable in 
the prefix. I suggest a leading G_ for 
variables that are global across modules 
(files) and are declared with the extern 
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lr^ RCTOS 

SYSTEMS CORPORATION 

X-Port Parallel Adapter 

Expand mass store capabilities 

Attach CD-ROM and SCSI based 
peripherals to a single parallel port 

Comes with drivers for DOS, MSDEX 

Low power, compact size 

For notebooks, laptops, desktops 

$226 + shipping & handling 

PO, Cheque, VISA 

300 March Rd., 4th Floor, 

Kanata, Ontario, Canada, K2K 2E2 
(613) 691-3084 (613) 691-1806 (fax) 
Dealer & OEM enquiries welcomed 


□ Request 101 on Reader Service Card □ 



"Highly recommended" - J. Dvorak, PC Magazine 
"Outstanding.,, lets you explore the creative 


possibilities of fractals" - Amstrad PC Magazine 
"Quick and easy to master" - New Scientist 
"Impeccably lucid... operations are fast" - BYTE 

Fractal programming tutorial, 160-page Guidebook, 
Microsoft C programs, 200+ modrtiable templates. 
Supports DXF and .PCX files, CGA to Super-VGA. 

Orders/Info: CALL 802-888-5275 

Cedar Software box 5140 -m. Morrisvme vt 05661 
□ Request 171 on Reader Service Card □ 


TUB " is FASTEST! 



RCS ,W 4.2 PVCS'“ TUB™ 3.0 TLIB™ 5.0 

Times are to update a 45K library on a PC/XT. PVCS and TLIB 3.0 are 
from Sept 87 PC Tech Journal. MKS RCS 4.2 and TLIB 5.0 are newer. 

TLIB™ is BEST! 

"Do not he fooled by the fact that this is the 
least expensive of the five packages reviewed 
here - TLIB has features and power to spare" 
John Rex, Computer Language 
"TLIB is a great system" J. Vallino, PC Tech J 

. Full-Featured Version Control for Software 
Professionals. Check-in/out locking. Branching. 
Keywords. Wildcard and list-of-file support. Can 
merge parallel changes and undo intermediate 
revisions. Network and WORM support. Main¬ 
frame compatible deltas for Pansophic, ADR, IBM, 
etc.. Integrates with Opus™ MAKE & Slick™ MAKE. 

MS-DOS $139, OS/2 $195 + shipping Visa/MC I 
5 station LAN license $419 (OS/2 $595), call for other sizes 

BURTON SYSTEMS SOFTWARE 

PO Box 4156, Cary, NC 27519 (919) 233-8128 

□ Request 137 on Reader Service Card □ 
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If you're reading this ad 
— you're one of 18,000 
programmers who read 
Windows/DOS monthly. 

Call (913) 841-1631 
today to reserve space 
for your ad. 


Opt-Tech Sort/Merge 


Extremely fast Sort / Merge / 
Select utility. Run as an MS- 
DOS command or CALL as a 
subroutine. 

Supports most languages and 
filetypes including Btrieve and 
dBase. Unlimited filesizes, mul¬ 
tiple keys and much more! 

MS-DOS $149. 

OS/2, UNIX $249. 


Opt-Tech Data Processing 

P. O. Box 678 
Zephyr Cove. NV 89448 

(702) 588-3737 


□ Request 127 on Reader Service Card □ 

December 1991 
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C/ANALYST 2. 


a 


Can bring you up to speed quickly 
on unfamiliar C source code. 

ANALYZE performs PROCTREE generates 

source code analysis large tree diagrams 

across multiple files. sideways. 

XREF generates a DATAFLOW shows how 

global cross reference data is passed between 

with read/write codes. modules. 

ALL FOR $250.00 

CALL FOR FREE 
ACTION DLAGRAMMER 
WITH DEMO OF C/ANALYST 

(503) 581-5622 


CATER SOFTWARE 


2182 Westfarthing Way NW 
Salem, OR 97304 


□ Request 321 on Reader Service Card □ 


FLOATING POINT 
ARRAY PROCESSOR 


* Operates on Arrays & Matrices; 
Integer, Real, & Complex Structures. 

* Process math-intensive algorithms 
100 times faster than the 80387. 

■k 598 mathematic & scientific functions 
on-board in EPROM, callable from C. 

* Private high speed STATIC memory 
(0.25 to 4.25 megabytes) on board. 

+ 3 megabytes/sec to/from ISA host. 

* Direct hardware link to video & A/Ds. 

* 1000 page reference manual. 

* $2495.00 complete with software. 

* Call for function list and benchmarks. 

Eighteen Eight Laboratories 

1-800-888-1119 FAX 702-294-2611 
1247 Tamarisk Lane 
Boulder City, NV 89005 

□ Request 150 on Reader Service Card □ 


Instant Microcontroller 

+ 

Instant C 


Instant New Product 

Use our Little Giant™ and Tiny Giant™ miniature 
microprocessor-based computers to instantly com¬ 
puterize your product. Our miniature controllers 
feature built-in power supplies, digital I/O, serial I/O 
(RS232 / RS485), A/D converters (to 20 bits), 
solenoid drivers, time of day clock, battery backed 
memory, watchdog, field wiring connectors, and 
more! Designed to be easily integrated with your 
hardware and software. Priced from $159. Core 
modules as low as $59. Low cost, interactive Dy¬ 
namic C™ makes serious software development 
easy. 

Z-World Engineering 

1724 Picasso Ave., Davis, CA 95616 USA 

Tel: (916) 753-3722 Fax: (916) 753-5141 

Automatic Fax: (916)753-0618 
(Call from your fax. request catalog #18) 


□ Request 279 on Reader Service Card □ 



DEVELOPERS! 

AE^AOFIEPZ! 

GOING INTERNATIONAL? 

Our string extemalization utilities and C 
functions can help you get your package ready 
for the intemational market. 

These proven utilities extract literal strings 
from your C source code, ready for editing, 
translation or encryption, without impacting 
your original executable. While saving scarce 
initialized data space, these functions allow 
your easily re-denned prompts to behave as if 
they were compiled directly into your program. 
Tins permits the original executable to "speak" 
the language of your choice, even Japanese! 

Includes all object/source code and libraries 
for popular C compilers. Price $149.95 forob- 
ject, $249.95 for source code site license. No 
royalties. DOS, Unix, Mac, etc. VA residents 
arid sales tax. 

Network Dynamics, Inc. 

2225 S. Henry Street, Suite L-2 
Williamsburg, VA 23185 
Phone (804) 220-8771 Fax (804) 220-5741 

□ Request 149 on Reader Service Card □ 

December 1991 



IMPACT VI.0 
Image Processing 

* Image Enhancement 

* Image Restoration 

* 2-D Data Analysis 

* Object Segmentation 

* Pattern Recognition 


IMPACT V1.0 is a completely integrated image processing 
system containing over 12 Mbytes of programs (> 120 funcs) 
designed to run on any basic PC/AT without special 
hardware . It contains all basic math + Boolean functions, 2-D 
FFTs, (de)convolution, bandpass filtering, edge 
enhancements, editable filter masks, RGB color mapping, 
Riemann mapping, 3-D stereoscopic projections, non-linear 
contrast stretching, thresholding and re-normalization, 
contour and area integrals, ROI statistics, pixel-line plots. 


etc, etc. 


$225 

(FREE upgrade to V2.0) 

$4.50 S&H, NM add 5.875% 

TARDIS Systems Inc. 

945 San Ildefonso, Suite 15 
Los Alamos, NM 87544 

Voice+FAX: (505) 662-9401 
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WINDOWS & DOS DEVELOPERS ! 

DataLIB Reads & Writes 
SPREADSHEET, DATABASE and ASCII FILES 
Use DataLIB to add advanced data import/export 
features to your Windows and DOS applications. 
DataLIB can read |& write Lotus 123 (WKS, WK1, 
WK3), Excel (XLS), dBASE (DBF), DIF, SYLK, Quattro 
(WQK) and ASCII (CSV, TXT, TAB) data files - all with 
the same set of function calls! A single function call 
converts a file to a different data format! Data types 
include string, char, boolean, integer, real, and 
date/time. Formats includes decimal, scientific, 
alignment, currency, percent, comma, and sign. Access 
entire files or individual cells or fields. Support new 
formats with almost no source code change. DataLIB is 
a very simple yet powerful library! DataLIB/Windows is 
a set of Dynamic Link Libraries callable from C, C++, 
Actor, Realizer, C, Smalltalk, Visual Basic, Word, 
AmiPro, Plus, ToolBook, Turbo Pascal/Windows, and 
most systems that support DLL calls. DataLIB/DOS is 
available for Microsoft C, Borland C+ + and Turbo C . 

NO ROYALTIES ! 

Only $395 gets you everything ! 

To Order Call: 1-800-ASK-4-DATA 

For Information Call: (215) 564-5577 
DatTel Communication Systems, Inc. 

3508 Market Street, Suite 415, Phiadelphia, PA 19104 

□ Request 151 on Reader Service Card □ 


32-bit Protected Mode 
386 C Graphics Library 

Intel 386/486 C Code Builder 
MetaWare, MicroWay, SVS, 
Watcom & Zortech with 
Phar Lap 3861 ASM 

Mixed Raster/Vector, 
Scalable, Rotatable Font, 
VGA, SVGA, 8514/A, VESA, 

Hercules Graphics Station 
through 1024x768x256 (8-bit), 
640x480x32k (16-bit), 
512x480x16.7m (32-bit), 
WYSIWYG HP-GL/PostScript 
$200 NO ROYALTIES 
FULL SOURCE CODE 
Gary R. Olhoeft 
P.O. Box 10870 Edgemont 
Golden, CO 80401-0620. 
303-877-3697 CIS 76665,2021 

□ Request 294 on Reader Service Card □ 


SOFTWARE & HARDWARE 
Development 


•Software ‘Firmware 
‘Designs ‘Reviews 


TARDIS Systems Consulting Group 

***************************************** 

Why not get the BEST? We represent a group of top- 
notch highly motivated scientists and engineers from one 
of this countries leading national labs. They want to 
market their skills in the private sector. 

***************************************** 

Dr. Christopher A. Ciarcia 
TARDIS Systems Inc. 

945 San Ildefonso, Suite 15 
Los Alamos, NM 87544 
Voice + FAX: (505) 662-9401 


□ Request 153 on Reader Service Card □ 
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keyword. A g_ can be used for variables 
that are global within a single module 
and declared with the static keyword. I 
do not add a prefix to automatic vari¬ 
ables or variables that are declared 
static within a block or function. I am 
not trying to force a standard on 
anyone. This is just what I have found 
to work well for me. If you do not like 
the G_ and g_ try e_ and s_ or 
whatever. Just be consistent with a 
convention once you adopt it 

I also have a list of criteria for 
naming identifiers that I and all the 
programmers I work with use. It repre¬ 
sents a sane and realistic approach to 
naming variables. The goal is meaning 
and readability. This is in contrast to 
Hungarian notation. This approach does 
not apply just to variable names, but 
should be used for all identifiers - in¬ 
cluding function names, macros, and 
types. Properly naming your types, 
macros, functions and variables makes 
a program nearly self-documented. 
Memorable - Make all identifier names 
easy to remember. 

Quantifiable - Use similar names for 
similar quantities. You should be able to 
derive meaning from the name. 
Automatic - Use your first impression. 
Do not spend too much time coming up 
with a name. If it takes too long to 
come up with a name, it probably will 
not be memorable or yield much 
meaning. 

Concise - A long bad name is worse 
than a short bad name. You can make 
multiword names readable by mixing 
case or inserting underscore characters 
as delimiters. Try to limit multiword 
names to three words maximum. If you 
abbreviate words, use standard ab¬ 
breviations or abbreviate by first 
removing vowels. 

Consistent - Come up with a conven¬ 
tion that you use throughout a project. 
Decide from the beginning such issues 
as mixed case, underscores, length, 
prefixes, suffixes, Hungarian notation, 
etc. Once you decide on a convention 
stick with it. 

This list was inspired by someone 
else's list Unfortunately, I do not know 
what publication it came from or who 
to credit But I give thanks to whoever 
first penned these ideas. I hope there 
are other readers who will appreciate 
these guidelines as much as I have. 

William Smith 
Engineering Manager 
Montana Software 
P.O. BOX 663 
Bozeman, MT 59771-0663 

I expected that inflammatory 
editorial about Hungarian notation to 
generate at least a dozen letters from 
the pro-Hungarian forces. Instead, I 


have only heard from people who 
agree with me. 

Please note that the Hungarian 
notation (as defined by its author) has 
two parts. Encoding the type in the 
name is just one part. The part I in¬ 
tended to rail against is that the 
mnemonic part of the name is unim¬ 
portant and may be omitted. Thus, a 
name like zsxcdWindowPos does not 
follow the notation. 

I'm fascinated at how obsessed we 
become about coding standards 
whenever two or more programmers 
are gathered together into a team. The 
problem is, coding conventions have 
never been shown to significantly in¬ 
crease code quality. 

One thing that definitely does in¬ 
crease code quality is peer code 


reviews, yet I've only worked in one 
company that used code reviews, and 
I initiated them. We find coding stand¬ 
ards attractive because, as program¬ 
mers, we like the idea of a set of 
deterministic rules. Successful peer 
code reviews, by contrast, require at¬ 
tention to non-deterministic social is¬ 
sues in order to create an environment 
where people can critique each other 
in a non-threatening way. They also 
can’t be imposed by management; the 
people writing the code have to want 
the code review for it to be effective. I 
think Larry Constantine (the father of 
Structured Design, who left the busi¬ 
ness to become a family therapist for 
10 years) is right: the most important 
programming problems are people 
problems, -rib 
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CopyControl 
COPY PROTECTION 


Control your profits with the copy protection designed 
with strength, user-transparency and compatibility. 

• Beats ALL the bit-copiers & Dis-assemblers 

• No hardware plugs or special disks required 

• Encrypts your program & adds anti-debug code 

• Allows you to produce full function demos 

• Compatible with LAN, backups & disk utilities 

• Supports all Floppy & Hard disk formats 

• Allows you to change parameters remotely. 
Control when, where, and how your software is ran. 
Compatible with all IBM/DOS Computers. 

$595 Unlimited Version. 30 day Money back guarantee 
bb Also available by Meter Count ISK] 
i^a.1 Free Demo & Into- COD «P0 W 


llicrocosm Inc. 

Drawer 0, Wellington, MO 64097 

(800) 237-8400 ext. 212 
(816) 934-8384 / Fax (816) 934-2617 

□ Request 162 on Reader Service Card □ 


The Upper Deck Editor 

A Serious Editor For Windows 3.0 

Edits files larger than 64K, real 
UNDO (300 levels), regular expres¬ 
sions, search across multiple files, 
split-screen file comparison, com¬ 
piler support, keyboard macros, fully 
customizable. 

INTRODUCTORY PRICE $75 

Call for our fully functional 

DEMO DISK! 

(619) 741-1075 

Upper Deck Systems 

P.O. Box 2751, Escondido, CA 92033 
□ Request 350 on Reader Service Card □ 


Speed Up Development With: 
Programmer’s SUPER-MAINT** T “ 

SUPER-MAINT builds your make and 
response files, remembers your command 
flags, the make file name, and more! 
SUPER-MAINT works for you so you can 
focus where you need to: on your 
programming! Still only $55 1 + 250 t&h. NY 

resident! add tales tax). 

7 can't toff you bow niffy this thing is.' Jcaepb Stars, UfhData 

Make File Builder Supports Microsoft, Borland, Aztec, 
Clipper, Mix languages: just "point and shoot" at code 
files you want ia your program, multiple setups, user 
configurable. Free CompuServe Intro Pak with 
purchase. 

EmmaSoft 
PO Box 238 
Lansing, NY 14882 

Voice: (607) 533-4685 
BBS: (607) 533-7072 

s s 
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FIX 80386 



SAVES YOUR PC 


The FIX-80386 solves the Errata 21 timing problem 
that is showing up on many PC's. IF your PC locks up 
when running UNIX or AUTOCAD, HP BASIC, MICRO 
CADAM PLUS or memory extenders in MS-DOS you 
will need this part. The part is placed between the 80386 
and its socket. Constructed of gold pins and sockets for 
highest quality. Available immediately. ALSO ASK 
ABOUT OUR UNIQUE SOLUTIONS FOR PROBING 
PGA's, PLCC's and LCC's. 

IRONWOOD ELECTRONICS <— 

P.O. BOX 21151. ST. PAUL. MN 55121 1 fj 

(612)431-7025; FAX (612) 432-8616 C-S— 1 
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C Network 
Library 


Over 300 functions providing NetWare 
system services and statistics including: 


• accounting 

• bindery 

• connection 

• console 

• directory 

• file 

• file server 

• IPX comm. 


• locking 

• message 

• print 

• queue mgt. 

• security 

• semaphore 

• trans. tracking 

• work station 


Over 100 sample programs including 
source code for most of the NetWare 
command line utilities (such as capture, 
nprint and logout) and reports. Plus 
over 400 pages of documentation. 

8188 S. StRt 48, #6 
Maineville, OH 45039 

1-800-669-0842 
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Disassemble MS-Windows 
Executables with... 

• Creates detailed assembly oode listings 
from MS-Windows 3.x executable files. 

• Identifies program segmentation, 
automatically! 

• Labels Window's API calls and exported 
functions, automatically! 

• Fast forward to references to specific 
Win API calls or module entry points. 

• Extracts just the function you need using 
a disassembly range. 

• Provides batch interface to define 
descriptive names and type information 
using a response file. 

• Supports 8086 - 80386. 

• Requires MS-DOS 3.x or newer. 


Man, 


\./Di*k $74.95 + S/H($2US/$5lnH) 
Call or FAX (408)262-3264 
3Q-Day Monoy Back Guarantee 



Eclectic Software 

937 Jungfrau Court 
Milpitas, CA 95035 USA 
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IKTEL® 80486 
MACRO DISASSEMBLER 

MD86 (Masterful Disassembler) is the 
most comprehensive macro disassembler 
on the market. Interactive by design not 
after-thought. Features include: 


► User defined macros with arguments 

► Auto code/data separation 

► Auto commenting and label naming 

► Command menus and help screens 

► Customizable disassembly options 

► Comprehensive, indexed, manuals 

► Fully supports 8086/87 thru 80486/87 

► COM/EXE/SYS/memory/othe^ 

► Cross reference and more! 

Still only $67.50 + tax ($1.50 s/h) 

C.C.SOFTWARE 
1907 ALVARADO AVE. 

WALNUT CREEK. CA 94596 
(510)939-8153 



So you want to write a hot Windows video game and 
make the big money. The problem is, you don't 
have a sprite animator. Don't tret. Use ours. 

WANIM.DLL 

The Windows 3.0 Sprite Animator 

From 

AND-XOR Systems 


• Animate sprites on a colored background within a 
window, using multiple animation zones. 

- Great fa screen savers, games, education, multimedia. 

• Algorithmic and bitmap sprites. 

• Automatic masks generation from sprite images. 

• Change display priorities on the fly. 

• Background scroll. 

• Collision detection. 

- Fast multitasking DLL. 

• Use with any Windows 3.0 compatible language. 

• Use with MS Windows Multimedia Extensions. 

■ Only $69. With source $99. No Royalties. Free demo. 



1107 Fair Oaks Ave 
Suite 167 

Souti Pasadena, CA 91030 
(213)969-4081 
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Scalable fonTS 


EXCLUSIVE! Integrate the FesfFonf Typeface Hath 

ager object library into your application to add fast, 
WYSIWYG, on-the-fly printer and display fonts. Includes 
the three most popular hinted font families. 300+ fonts 
available. Only $495 with NO ROYALTIES. Optional 
Printer Driver Platform, Font Conversion Utilities, et al. 

^ Ancier 

Technologies, Inc. 
Sk 5964 La Place Ct„ #125 
Carlsbad, CA 92008 
Ph: 619/438-5004x132 
Fax: 619/438/6898 
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NETWORK 

CONTROL 

LIBRARIES 

NETBIOS ROUTINES allows ac¬ 
cess to low-level network func¬ 
tions. Name, session, and 
datagram routines. Wait and no¬ 
wait options. $99 

NETWORK MASTER provides 
access to Netware internal func¬ 
tions. Complete network control 
from your compiled programs! $99 

Starlight Software 

P.O. Box 1090 
Wheeling, IL 60090 
(708) 394-0622 
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WRITE SOFTWARE 
WITHOUT LANGUAGE 

Software made 6USy. 

Professionals, Scientists, 
Engineers, Technicians. 

M-Code $179.00 
A tool to write software for the 

8088 family, 8051 family 

and other processors 

Call or send for data sheet 

T'V/"'VQ Box 4601 Carmel CA 93921 
LJLJlJystems (408) 625 9016 

□ Request 178 on Reader Service Card □ 


SDLC, HDLC 
And X.25 Support 

Use Sangoma hardware and software 
to provide fast, cost effective, robust 
and easy to use SDLC, HDLC and X.25 
links from MS-DOS, UNIX, Concurrent 
DOS etc. 

All real time communication functions 
are performed by intelligent coproces¬ 
sor card. Line speeds up to 160 kbps 
are supported. Powerful debugging, 
line statistics and trace facilities are 
included. 

Full function SNA emulation packages 
also available. 

Sangoma Technologies Inc. 

» (416) 474-1990 
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MS dos System 
Programming 


Second edition 


2nd Edition 


Edited by Robert Ward 
NOW-You can get the Informa¬ 
tion most programmers don’t 
even know about. 

PLUS —Gain access to a critical 
bibliography that will become an 
indispensible resource to you. 

HIGHLY TECHNICAL 
HIGHLY FOCUSED 


MS-dos 

system programming 


Every entry is written by 
working programmers for 
working programmers. In¬ 
cluded are compiler- 
specific insights that will 
save you hours of work. 

Find out how to exploit spe¬ 
cial Turbo C features to 
simplify device drivers. Plus 
a bibliography designed to 
help the serious program¬ 
mer develop a personal 
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Nitty Gritty Coverage on 
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FREE 

Product 

Information 

Use this postage paid 
card to stay up to date 
on products 
that affect 
your productivity. 

Just fill out the card at 
the right and 
drop it in the mail. 



□ DEVELOPER'S JOURNAL 

Please help us serve you by 
answering the following: 

1) I program: 

□ for a living 

□ as a hobby 

□ as a manager 

2) I program in: 

□ MS-DOS 

□ Macintosh 

□ Xenix/UNIX 


1601 W. 23rd. St., Ste. 200 
P.O. Box 3127 
Lawrence, KS 66046-9943 
(913) 841-1631 FAX: (913) 841-2624 

REQUEST READER SERVICE NUMBERS: 



NAME 


3) I program most frequently in: 

□ Assembly 

□ Pascal MS- 

□ BASIC 

□ C CITYISTATEIZIP 

□ Other _ 

□ Please send me subscription information. 
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U DEVELOPER'S JOURNAL 

□ YES! Send me 12 issues of Windows/DOS Developer’s Journal for only $29! 

□ 2 years (24 issues) for $54 □ 3 years (36 issues) for $77 

□ Bill Me □ Visa □ MasterCard 
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Please allow up to six weeks for delivery of first issue. Orders outside the US must be prepaid in US funds. CANADA/MEXICO 
subscriptions are: 1 year - $38; 2 years - $63; 3 years - $86. Overseas subscriptions are: 1 year - $48; 2 years - $88; 3 years - $126. 
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BAT 


MSTALL 3* CMS YOUR SOFTWARE PRODUCT 
A PROFESSIONAL INTRODUCTION, 


Installation procedures that rely on 
batch files and DOS commands not 
only look amateurish but also have 
limited error handling capabilities. 
Today's users expect quality and ease 
of use from software — beginning the 
moment they open the package. A 
smooth, professional installation 
makes an important first impression. 

EVERYTHING YOU NEED 

INSTALL 3.0 is customized for your 
product with an ASCII text file called 
a "script file." INSTALL 3.0 comes 
with many sample script files that you 
can modify and use immediately. No 
programming is necessary to create 
most installations. However, C source 
code is included for your convenience 
and technical support is free. 

FAST AND SIMPLE 

Use INSTALL 3.0 to create an elegant 
installation procedure that will 
increase users' confidence in your 
product. INSTALL 3.0 takes advan¬ 
tage of available RAM for lightning- 
fast file transfers. All your documen¬ 
tation has to tell users is TYPE 
"A: INSTALL". 


INSTALL PRO 

• Builds distribution disk sets 
automatically 

• Creates a configuration file, 
containing all parameters for 
each disk set 

• Automatically builds INSTALL 
script files 

• Automatically formats disks 
(360K, 720K, 1.2M, 1.44M) 

• Uses a full screen, point-and- 
shoot interface for fast, efficient 
file tagging 

• Automatically splits large files 
across multiple diskettes 

• Literally cuts distribution disk 
building time from days to 
minutes for complex products 


KNOWLEDGE DYNAMICS 

Corporation 

Highway Contract 4, Box 185-H 
Canyon Lake, Texas (USA) 
78133-3508 

□ Request 103 on Reader Service Card □ 


PROVEN RELIABILITY 

INSTALL 3.0 has been used for over 
four years by sojne of the biggest (and 
smallest!) names in the industry, in 
the U.S. and abroad, to install millions 
of copies of their programs. Add your 
name to the list today. 

30 DAY MONEY-BACK 
GUARANTEE 

Free technical siipport. No royalties. 
MasterCard/VISA/COD/POs 
welcome. 

$399.95 INSTALL PRO 
$249.95 INSTALL 3.0 
$99.95 International Option 
$99.95 OS/2 Option 

SALES 

1/800-331-2783 ext. #0194 

International 
1/512-964-3994 
24 hour FAX 1/512-964-3958 
24 hour BBS 1/512-964-3929 

CALL OR FAX BY NOON 
AND RECEIVE INSTALL 3.0 
TOMORROW! 








DISCOVER 

A WORLD OF MEMORY 
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Phar Lap's 386IDOS-Extender. 

Build multi-megabyte DOS programs with 
total Windows compatibility! 

! Chances are, if you develop high-performance software for 
the PC world, you've collided with the DOS 640K memory 
barrier. Now you can break through that barrier and still run 
your software in Windows 3.0 enhanced mode - with Phar 
leap's 386IDOS-Extender Software Development Kit (SDK). 

Unequalled compatibility. Other DOS extenders 
support just two or three of the five Extended-DOS standards 
currently in use. 


Only 386IDOS-Extender supports all five standards: 

I\T 15 VCPI XMS DPMI YDS 


Now you can write a single Extended-DOS application that will 
run under DOS, DESQview and all modes of Windows. 

□ Request 132 on Reader Service Card □ 


Access all available memory. Other DOS extenders 
can leave entire megabytes of memory unallocated. Only 
386IDOS-Extender finds all the unused memory in your 
computer, no matter what type of memory manager you have. 

How a DOS extender works. 386IDOS-Extender 
turns DOS into a true 32-bit operating system by functioning 
as a layer between DOS in real mode and your program in 
protected mode. With full 32-bit memory, speed and power, 
you can finally build multi-megabyte workstation-class 
applications for the PC. 

Because 386IDOS-Extender is embedded into your 
program, it is invisible to the end-user. Your program looks 
exactly like any other DOS application. There is no new 
operating system for your end-users to buy or learn. 

So if DOS is looking smaller than ever, call Phar Lap today. 

And discover the world beyond 640K. 

Phar Lap 386IDOS-Extender. 

We open a world of memory. ^ 


Phar Lap Software, Inc. 
60 Aberdeen Avenue 
Cambridge, MA 02138 
617-661-1510 
FAX 617-876-2972 


Trademark holders: 386IDOS-Extender™ — Phar Lap Software. Inc.: Windows™ — Microsoft Corp.; DESQview"' — Quarterdeck Office Systems. 
Registered trademark -holders: Phar Lap® — Phar Lap Software, Inc.; MS-DOS® and Microsoft® — ©1991 Phar Lap Software, Inc. 











